From d09a8c8f09fde30774b047dae8e52a91c4b858a4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 09:09:43 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/qa-e2e-automation.md | 213 +++--- docs/uk/help/testing.md | 947 +++++++++++++------------- 2 files changed, 578 insertions(+), 582 deletions(-) diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index d51c3773d..f2083d79c 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -2,14 +2,14 @@ read_when: - Розширення qa-lab або qa-channel - Додавання сценаріїв QA з підтримкою репозиторію - - Побудова більш реалістичної автоматизації QA навколо панелі керування Gateway + - Побудова реалістичнішої автоматизації QA навколо панелі Gateway summary: Приватна форма автоматизації QA для qa-lab, qa-channel, сценаріїв із початковими даними та звітів протоколу title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-20T02:15:03Z" + generated_at: "2026-04-23T09:05:07Z" model: gpt-5.4 provider: openai - source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 + source_hash: a967a74d2e70b042e9443c5ec954902b820d2e5a22cbecd9be74af13b9085553 source_path: concepts/qa-e2e-automation.md workflow: 15 --- @@ -17,20 +17,21 @@ x-i18n: # Автоматизація QA E2E Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, -каналоподібний спосіб, ніж це може зробити один модульний тест. +орієнтований на канали спосіб, ніж це може зробити один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями для DM, каналу, треду, - реакції, редагування та видалення. -- `extensions/qa-lab`: UI для налагодження та шина QA для спостереження за транскриптом, - інʼєкції вхідних повідомлень і експорту Markdown-звіту. -- `qa/`: ресурси з початковими даними з підтримкою репозиторію для стартового завдання та базових сценаріїв QA. +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, + реакцій, редагування та видалення. +- `extensions/qa-lab`: UI налагодження та шина QA для спостереження за транскриптом, + інʼєкції вхідних повідомлень і експорту звіту у форматі Markdown. +- `qa/`: ресурси з початковими даними, що зберігаються в репозиторії, для стартового завдання та базових + сценаріїв QA. -Поточний робочий процес оператора QA — це сайт QA з двома панелями: +Поточний потік роботи оператора QA — це сайт QA з двома панелями: -- Ліворуч: панель керування Gateway (Control UI) з агентом. -- Праворуч: QA Lab, де показано транскрипт у стилі Slack та план сценарію. +- Ліворуч: панель Gateway (Control UI) з агентом. +- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. Запустіть його так: @@ -40,10 +41,10 @@ pnpm qa:lab:up Це збирає сайт QA, запускає лінію Gateway на базі Docker і відкриває сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, -спостерігати реальну поведінку каналу та записувати, що спрацювало, що не спрацювало або -що залишилося заблокованим. +спостерігати реальну поведінку каналу та фіксувати, що спрацювало, що не спрацювало або +залишилося заблокованим. -Для швидшої ітерації UI QA Lab без повторного збирання Docker-образу щоразу +Для швидшої ітерації UI QA Lab без перебудови Docker-образу щоразу запустіть стек із bind-mounted збіркою QA Lab: ```bash @@ -53,11 +54,12 @@ 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` -перезбирає цю збірку при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. +перебудовує цю збірку при зміні, а браузер автоматично перезавантажується, коли +змінюється хеш ресурсів QA Lab. -Для транспортно-реалістичної лінії smoke для Matrix виконайте: +Для smoke-лінії Matrix із реальним транспортом виконайте: ```bash pnpm openclaw qa matrix @@ -65,67 +67,68 @@ pnpm openclaw qa matrix Ця лінія розгортає одноразовий 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=` на файл журналу всередині репозиторію. +реальний Plugin Matrix всередині дочірнього процесу Gateway QA. Лінія з живим транспортом +утримує конфіг дочірнього процесу обмеженим транспортом, що перевіряється, тому Matrix працює без +`qa-channel` у конфігу дочірнього процесу. Вона записує структуровані артефакти звіту та +обʼєднаний лог stdout/stderr у вибраний каталог виводу Matrix QA. Щоб +також захопити зовнішній вивід збірки/запуску `scripts/run-node.mjs`, встановіть +`OPENCLAW_RUN_NODE_OUTPUT_LOG=` у лог-файл усередині репозиторію. -Для транспортно-реалістичної лінії smoke для Telegram виконайте: +Для smoke-лінії Telegram із реальним транспортом виконайте: ```bash pnpm openclaw qa telegram ``` Ця лінія націлюється на одну реальну приватну групу Telegram замість розгортання -одноразового сервера. Вона вимагає `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +одноразового сервера. Для неї потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також двох різних ботів в одній -приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а спостереження бот-до-бота -працює найкраще, коли в обох ботів увімкнено Bot-to-Bot Communication Mode +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також два різні боти в одній +приватній групі. Бот SUT має мати імʼя користувача Telegram, а спостереження +bot-to-bot працює найкраще, коли в обох ботів увімкнено Bot-to-Bot Communication Mode у `@BotFather`. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. +Звіт і підсумок Telegram містять RTT для кожної відповіді — від запиту на надсилання повідомлення driver +до спостережуваної відповіді SUT, починаючи з canary. -Тепер лінії живого транспорту мають один спільний менший контракт замість того, щоб кожна +Тепер лінії з живим транспортом використовують один менший контракт замість того, щоб кожна вигадувала власну форму списку сценаріїв: -`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту і не входить +`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту й не входить до матриці покриття живого транспорту. -| Лінія | 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 та майбутні живі транспорти мають один явний контрольний список транспортного контракту. +Telegram і майбутні живі транспорти використовують спільний явний контрольний список транспортного контракту. -Для одноразової лінії Linux VM без залучення Docker до шляху QA виконайте: +Для одноразової лінії Linux VM без використання Docker у QA-шляху виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` Це завантажує нову гостьову систему Multipass, встановлює залежності, збирає OpenClaw -усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт QA та -підсумок назад у `.artifacts/qa-e2e/...` на хості. -Вона повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. -Запуски suite на хості й у Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими воркерами gateway. `qa-channel` за замовчуванням має concurrency 4, +усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт і підсумок QA назад у `.artifacts/qa-e2e/...` +на хості. +Вона використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. +Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно з ізольованими worker-процесами Gateway. `qa-channel` за замовчуванням використовує конкурентність 4, обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість воркерів, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо +кількість worker-процесів, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. -Живі запуски пересилають підтримувані вхідні дані автентифікації QA, які практично -використовувати в гостьовій системі: ключі провайдера через env, шлях до конфігурації живого провайдера QA і +Живі запуски передають підтримувані вхідні дані автентифікації QA, які практичні для +гостьової системи: ключі провайдера через env, шлях до конфігу провайдера QA live та `CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість -міг записувати дані назад через змонтований workspace. +міг записувати назад через змонтований workspace. -## Початкові дані з підтримкою репозиторію +## Початкові дані з репозиторію -Ресурси з початковими даними зберігаються в `qa/`: +Ресурси з початковими даними знаходяться в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` @@ -133,24 +136,22 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. -`qa-lab` має залишатися загальним виконавцем markdown. Кожен markdown-файл сценарію є -джерелом істини для одного тестового запуску та має визначати: +`qa-lab` має залишатися загальним runner-ом Markdown. Кожен Markdown-файл сценарію є +джерелом істини для одного тестового запуску й має визначати: - метадані сценарію -- необовʼязкові метадані категорії, можливості, лінії та ризику -- посилання на docs і код +- необовʼязкові метадані категорії, можливостей, лінії та ризику +- посилання на docs і code - необовʼязкові вимоги до Plugin -- необовʼязковий patch конфігурації gateway +- необовʼязковий patch конфігурації Gateway - виконуваний `qa-flow` -Багаторазова поверхня виконання, яка лежить в основі `qa-flow`, може залишатися загальною -і кросфункціональною. Наприклад, markdown-сценарії можуть поєднувати допоміжні засоби -з боку транспорту з допоміжними засобами з боку браузера, які керують вбудованим Control UI через -поверхню Gateway `browser.request`, не додаючи спеціалізованого виконавця. +Повторно використовувана поверхня runtime, що стоїть за `qa-flow`, може залишатися загальною +та наскрізною. Наприклад, Markdown-сценарії можуть поєднувати transport-side +хелпери з browser-side хелперами, які керують вбудованим Control UI через +поверхню Gateway `browser.request`, не додаючи спеціалізований runner. -Файли сценаріїв слід групувати за можливостями продукту, а не за папкою дерева -вихідного коду. Зберігайте ідентифікатори сценаріїв стабільними, коли файли переміщуються; використовуйте `docsRefs` і `codeRefs` -для трасування реалізації. +Файли сценаріїв слід групувати за можливостями продукту, а не за папкою вихідного дерева. Зберігайте стабільність ID сценаріїв при переміщенні файлів; використовуйте `docsRefs` і `codeRefs` для відстежуваності реалізації. Базовий список має залишатися достатньо широким, щоб охоплювати: @@ -160,51 +161,49 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline - зворотні виклики Cron - виклик памʼяті - перемикання моделей -- передавання підзадачі субагенту +- передачу підагенту - читання репозиторію та docs -- одне невелике завдання зі збирання, наприклад Lobster Invaders +- одне невелике завдання зі збірки, наприклад Lobster Invaders -## Лінії mock провайдерів +## Лінії з mock-провайдерами -`qa suite` має дві локальні лінії mock провайдерів: +`qa suite` має дві локальні лінії з mock-провайдерами: -- `mock-openai` — це сценарійно-орієнтований mock OpenClaw. Він залишається типовою - детермінованою лінією mock для QA з підтримкою репозиторію та перевірок паритету. +- `mock-openai` — це scenario-aware mock OpenClaw. Вона лишається типовою + детермінованою mock-лінією для QA з підтримкою репозиторію та перевірок паритету. - `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколу, - фікстур, record/replay та chaos. Це доповнення, а не заміна диспетчера сценаріїв `mock-openai`. + фікстур, record/replay і chaos. Вона є додатковою й не замінює dispatcher сценаріїв `mock-openai`. -Реалізація ліній провайдерів розміщена в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделей gateway, -потребами підготовки профілів автентифікації та прапорцями можливостей live/mock. Спільний код suite і -gateway має маршрутизувати через реєстр провайдерів замість розгалуження за назвами провайдерів. +Реалізація ліній провайдера знаходиться в `extensions/qa-lab/src/providers/`. +Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігом моделі Gateway, +потребами staging для auth-profile, а також прапорцями можливостей live/mock. Спільний код suite і Gateway має маршрутизувати через registry провайдерів замість розгалуження за іменами провайдерів. ## Адаптери транспорту -`qa-lab` володіє загальною транспортною поверхнею для markdown-сценаріїв QA. +`qa-lab` володіє загальною поверхнею транспорту для Markdown-сценаріїв QA. `qa-channel` — перший адаптер на цій поверхні, але ціль дизайну ширша: -майбутні реальні або синтетичні канали мають підключатися до того самого виконавця suite -замість додавання виконавця QA, специфічного для транспорту. +майбутні реальні або синтетичні канали мають підключатися до того самого runner-а suite замість додавання транспортно-специфічного runner-а QA. -На рівні архітектури розподіл такий: +На рівні архітектури поділ такий: -- `qa-lab` володіє загальним виконанням сценаріїв, паралельністю воркерів, записом артефактів і звітністю. -- адаптер транспорту володіє конфігурацією gateway, готовністю, спостереженням за вхідними та вихідними подіями, транспортними діями та нормалізованим станом транспорту. -- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову поверхню виконання, яка його виконує. +- `qa-lab` володіє загальним виконанням сценаріїв, конкурентністю worker-процесів, записом артефактів і звітністю. +- адаптер транспорту володіє конфігом Gateway, готовністю, спостереженням за вхідними та вихідними подіями, транспортними діями й нормалізованим станом транспорту. +- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану поверхню runtime, яка їх виконує. -Орієнтовані на мейнтейнерів вказівки з упровадження нових адаптерів каналів розміщені в +Орієнтовані на maintainer-ів рекомендації з упровадження нових адаптерів каналів знаходяться в [Testing](/uk/help/testing#adding-a-channel-to-qa). ## Звітність -`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. -Звіт має відповідати на запитання: +`qa-lab` експортує звіт протоколу у форматі Markdown зі спостережуваної часової шкали шини. +Звіт має відповідати на такі питання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим - Які подальші сценарії варто додати -Для перевірок характеру й стилю запустіть той самий сценарій для кількох живих ref моделей +Для перевірок характеру та стилю виконайте той самий сценарій на кількох live ref моделей і запишіть оцінений Markdown-звіт: ```bash @@ -224,35 +223,35 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії оцінювання характеру -мають задавати persona через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, -такі як чат, допомога з workspace та невеликі файлові завдання. Моделі-кандидату +Команда запускає локальні дочірні процеси Gateway QA, а не Docker. Сценарії оцінки характеру +мають задавати persona через `SOUL.md`, а потім виконувати звичайні ходи користувача, +такі як чат, допомога з workspace і невеликі файлові завдання. Моделі-кандидату не слід повідомляти, що її оцінюють. Команда зберігає кожен повний -транскрипт, записує базову статистику запуску, а потім просить моделі-суддів у швидкому режимі з -міркуванням `xhigh` ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` при порівнянні провайдерів: підказка для суддів усе одно отримує -кожен транскрипт і статус запуску, але ref кандидатів замінюються на нейтральні -мітки, такі як `candidate-01`; після парсингу звіт зіставляє рейтинги назад із реальними ref. -Запуски кандидатів за замовчуванням використовують рівень мислення `high`, а для моделей OpenAI, які це підтримують, — `xhigh`. -Щоб перевизначити конкретного кандидата, використовуйте inline-форму -`--model provider/model,thinking=`. `--thinking ` і надалі задає -глобальне резервне значення, а старіша форма `--model-thinking ` зберігається +транскрипт, записує базову статистику запуску, а потім просить моделі-судді в режимі fast з +міркуванням `xhigh` ранжувати запуски за природністю, vibe і гумором. +Використовуйте `--blind-judge-models` при порівнянні провайдерів: prompt судді все одно отримує +кожен транскрипт і статус запуску, але ref кандидатів замінюються нейтральними +мітками, такими як `candidate-01`; звіт зіставляє ранжування з реальними ref після +розбору. +Для запусків кандидатів за замовчуванням використовується рівень thinking `high`, а для моделей OpenAI, що це підтримують, — `xhigh`. Перевизначте конкретного кандидата inline через +`--model provider/model,thinking=`. `--thinking ` як і раніше задає +глобальне резервне значення, а старіша форма `--model-thinking ` збережена для сумісності. -ref кандидатів OpenAI за замовчуванням працюють у швидкому режимі, щоб використовувати пріоритетну обробку там, -де це підтримується провайдером. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли -одному кандидату або судді потрібно перевизначення. Передавайте `--fast`, лише якщо хочете -примусово ввімкнути швидкий режим для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів -записується у звіт для аналізу продуктивності, але підказки для суддів прямо кажуть +Для ref кандидатів OpenAI за замовчуванням використовується режим fast, щоб задіяти пріоритетну обробку там, +де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли +окремому кандидату або судді потрібно перевизначення. Передавайте `--fast`, лише якщо хочете +примусово ввімкнути режим fast для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +фіксується у звіті для аналізу продуктивності, але prompt-и суддів явно вказують не ранжувати за швидкістю. -Запуски моделей-кандидатів і моделей-суддів за замовчуванням обидва використовують concurrency 16. Зменшуйте -`--concurrency` або `--judge-concurrency`, коли ліміти провайдера чи навантаження на локальний gateway +І для кандидатів, і для моделей-суддів за замовчуванням використовується конкурентність 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, якщо ліміти провайдера або навантаження локального Gateway роблять запуск надто шумним. -Коли не передано жодного кандидата `--model`, character eval за замовчуванням використовує +Якщо не передано жодного `--model` кандидата, character eval за замовчуванням використовує `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і -`google/gemini-3.1-pro-preview`, якщо не передано `--model`. -Коли не передано `--judge-model`, за замовчуванням як судді використовуються +`google/gemini-3.1-pro-preview`, якщо `--model` не передано. +Якщо не передано жодного `--judge-model`, судді за замовчуванням: `openai/gpt-5.4,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. @@ -260,4 +259,4 @@ ref кандидатів OpenAI за замовчуванням працюють - [Testing](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) -- [Dashboard](/web/dashboard) +- [Dashboard](/uk/web/dashboard) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 0b77a68fb..73e98cb95 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,146 +3,146 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker runners і що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T07:54:35Z" + generated_at: "2026-04-23T09:05:10Z" model: gpt-5.4 provider: openai - source_hash: 647367fd0c3ea81bc3e8a7702c4a462cf4b9634989818f53153558edcf2218c1 + source_hash: fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runners. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: -- Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Що покриває кожен набір (і що він навмисно _не_ покриває) +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів - Як додавати регресійні тести для реальних проблем моделей/провайдерів ## Швидкий старт -У більшості випадків: +У більшість днів: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над окремим падінням спочатку віддавайте перевагу цільовим запускам. -- Сайт QA на базі Docker: `pnpm qa:lab:up` -- Лінія QA на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` +- QA-шлях на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви торкаєтеся тестів або хочете більшої впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Набір live (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` - Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live-перевірка моделей: `pnpm test:docker:live-models` - - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні +- Docker-обхід live-моделей: `pnpm test:docker:live-models` + - Покриття CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний `OpenClaw Release Checks` обидва викликають повторно використовуваний робочий процес live/E2E з - `include_live_suites: true`, який включає окремі matrix jobs Docker live model, - розподілені за провайдерами. - - Для цільових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, який включає окремі матричні завдання Docker live model, + розшардовані за провайдером. + - Для цільових повторних запусків у CI запускайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його запланованих/релізних викликів. -- Cost smoke для Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований +- Smoke-перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, потім виконайте ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6, а - транскрипт помічника зберігає нормалізоване `usage.cost`. + transcript помічника зберігає нормалізований `usage.cost`. -Порада: коли вам потрібен лише один падний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. -## Спеціальні runners для QA +## QA-специфічні ранери Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм qa-lab: -CI запускає QA Lab у виділених workflow. `Parity gate` запускається для відповідних PR -і з ручного виклику з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного виклику з mock parity gate, live Matrix lane та -live Telegram lane під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` -запускає ті самі lane перед схваленням релізу. +CI запускає QA Lab у виділених робочих процесах. `Parity gate` запускається для відповідних PR +і через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний запуск із mock parity gate, live Matrix lane та +live Telegram lane, керованим Convex, як паралельними завданнями. `OpenClaw Release Checks` +запускає ті самі шляхи перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. + - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - workers Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежену - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість - workers, або `--concurrency 1` для старішої послідовної lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли + робочими процесами Gateway. `qa-channel` за замовчуванням використовує concurrency 4 + (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість робочих процесів, або `--concurrency 1` для старішого послідовного шляху. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. + - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття fixture і protocol-mock без заміни lane `mock-openai`, яка враховує сценарії. + покриття фікстур і протокольних mock-перевірок, не замінюючи сценарно-орієнтований шлях + `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині одноразової Linux VM Multipass. + - Запускає той самий набір QA у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, практичні для guest: - ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA та `CODEX_HOME`, + - Повторно використовує ті самі прапори вибору провайдера/моделі, що й `qa suite`. + - Live-запуски передають підтримувані вхідні дані автентифікації QA, які практично використовувати в guest: + ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний звіт і підсумок QA, а також логи Multipass у + - Записує звичайний QA-звіт + підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає сайт QA на базі Docker для операторської роботи з QA. + - Запускає QA-сайт на базі Docker для операторського стилю QA-роботи. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточного checkout, встановлює його глобально в - Docker, запускає неінтерактивний onboarding з OpenAI API key, типово налаштовує - Telegram, перевіряє, що ввімкнення plugin встановлює runtime-залежності на вимогу, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму lane - встановлення з пакета для Discord. + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивне onboarding з OpenAI API key, налаштовує Telegram + за замовчуванням, перевіряє, що ввімкнення plugin встановлює runtime-залежності за + потреби, запускає doctor і виконує один локальний хід агента проти mock-ендпойнта OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий шлях + packaged-install із Discord. - `pnpm test:docker:bundled-channel-deps` - - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/plugins через - редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає відсутніми runtime-залежності plugin, - які ще не налаштовані, що перший налаштований запуск Gateway або doctor - встановлює runtime-залежності кожного bundled plugin на вимогу, і що другий restart не + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, потім вмикає bundled channel/plugins через редагування конфігурації. + - Перевіряє, що виявлення setup залишає runtime-залежності + не налаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного bundled plugin за потреби, і що другий перезапуск не перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу npm-базову версію, вмикає Telegram перед запуском - `openclaw update --tag `, і перевіряє, що doctor кандидата - після оновлення відновлює runtime-залежності bundled channel без - postinstall-відновлення з боку harness. + - Також встановлює відомий старіший базовий npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата + після оновлення виправляє runtime-залежності bundled channel без + postinstall-виправлення з боку harness. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти одноразового homeserver Tuwunel на базі Docker. - - Цей хост QA сьогодні призначений лише для репозиторію/розробки. Упаковані встановлення OpenClaw не постачають - `qa-lab`, тому не надають `openclaw qa`. - - Checkout репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення plugin не потрібен. - - Підготовлює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній процес QA gateway з реальним 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/...`. + - Запускає шлях live QA Matrix проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Паковані встановлення OpenClaw не постачають + `qa-lab`, тому вони не надають `openclaw qa`. + - Checkouts репозиторію завантажують bundled runner напряму; окремий крок встановлення plugin не потрібен. + - Підготовлює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, потім запускає дочірній процес QA gateway з реальним Matrix plugin як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорів джерела облікових даних, оскільки цей шлях локально створює тимчасових користувачів. + - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT з env. + - Запускає шлях live QA Telegram проти реальної приватної групи з токенами ботів 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`, щоб увімкнути пулінгові lease. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли + - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Потребує двох різних ботів в одній приватній групі, при цьому бот SUT має мати Telegram username. + - Для стабільного спостереження бот-до-бота ввімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостереженої відповіді SUT. -Live transport lane спільно використовують один стандартний контракт, щоб нові транспорти не розходилися: +Шляхи live transport використовують один стандартний контракт, щоб нові транспорти не розходилися в поведінці: -`qa-channel` лишається широким синтетичним набором QA і не входить до matrix покриття live transport. +`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. -| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Команда help | +| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | | -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | | Matrix | x | x | x | x | x | x | x | x | | | Telegram | x | | | | | | | | x | @@ -150,22 +150,22 @@ Live transport lane спільно використовують один ста ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat -цьому lease, поки lane виконується, і звільняє lease під час завершення роботи. +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки шлях виконується, і звільняє оренду під час завершення роботи. -Еталонний scaffold проєкту Convex: +Базовий scaffold проєкту Convex: - `qa/convex-credential-broker/` Обов’язкові змінні середовища: -- `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`) Необов’язкові змінні середовища: @@ -175,14 +175,14 @@ QA lab отримує ексклюзивний lease із пулу на базі - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди maintainers (додавання/видалення/перелік пулу) потребують саме -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують +саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні CLI-команди для maintainers: +CLI-хелпери для maintainers: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -190,9 +190,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. +Використовуйте `--json` для machine-readable виводу в скриптах і утилітах CI. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Типовий контракт ендпойнта (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -210,7 +210,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -223,55 +223,55 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання каналу до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Щоб додати канал до markdown QA-системи, потрібні рівно дві речі: -1. Адаптер транспорту для каналу. -2. Набір сценаріїв, який перевіряє контракт каналу. +1. Транспортний адаптер для каналу. +2. Пакет сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий top-level QA command, коли спільний хост `qa-lab` може -керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, коли спільний хост `qa-lab` може +володіти цим потоком. -`qa-lab` володіє спільною механікою хоста: +`qa-lab` володіє спільною хостовою механікою: -- коренем команди `openclaw qa` +- кореневою командою `openclaw qa` - запуском і завершенням набору -- паралелізмом workers +- concurrency робочих процесів - записом артефактів - генерацією звітів - виконанням сценаріїв - compatibility aliases для старіших сценаріїв `qa-channel` -Runner plugins володіють транспортним контрактом: +Плагіни раннерів володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як вхідні події ін’єктуються +- як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти й нормалізований стан транспорту +- як надаються transcripts і нормалізований стан транспорту - як виконуються дії на основі транспорту -- як обробляється транспортно-специфічне скидання або очищення +- як обробляється транспортно-специфічний reset або cleanup Мінімальний поріг впровадження для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному шві хоста `qa-lab`. -3. Залишайте транспортно-специфічну механіку всередині runner plugin або harness каналу. -4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Залишайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoints. +2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. +3. Зберігайте транспортно-специфічну механіку всередині runner plugin або channel harness. +4. Монтуйте раннер як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI та раннера має бути за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні допоміжні функції сценаріїв для нових сценаріїв. -7. Зберігайте наявні compatibility aliases працездатними, якщо репозиторій не виконує навмисну міграцію. +6. Для нових сценаріїв використовуйте загальні scenario helpers. +7. Зберігайте роботу наявних compatibility aliases, якщо тільки в репозиторії не виконується навмисна міграція. Правило ухвалення рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного канального транспорту, залишайте її в цьому runner plugin або harness plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальну допоміжну функцію замість канально-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспортно-специфічним і чітко позначайте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного транспортного каналу, зберігайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використовувати більш ніж один канал, додайте загальний helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, зберігайте сценарій транспортно-специфічним і явно зазначайте це в контракті сценарію. -Бажані назви загальних допоміжних функцій для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -286,7 +286,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Compatibility aliases лишаються доступними для наявних сценаріїв, зокрема: +Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -294,69 +294,69 @@ Compatibility aliases лишаються доступними для наявн - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати загальні назви допоміжних функцій. -Compatibility aliases існують, щоб уникнути міграції в один момент часу, а не як модель для -написання нових сценаріїв. +У новій роботі над каналами слід використовувати загальні назви helper. +Compatibility aliases існують, щоб уникнути міграції в стилі flag day, а не як модель для +створення нових сценаріїв. ## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних запусків shard (`vitest.full-*.config.ts`) поверх наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Конфігурація: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації per-project для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, які покриває `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, конфігурація) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) + - Детерміновані регресійні тести для відомих помилок - Очікування: - - Запускається в CI - - Не потребує реальних ключів - - Має бути швидким і стабільним -- Примітка про projects: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує граф project нативного root `vitest.config.ts`, тому що цикл watch із кількома shard є непрактичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable файлів source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, метадані релізу й tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають валідацію extensions, тому що extensions залежать від цих core-контрактів. Оновлення версій, що зачіпають лише метадані релізу, запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем top-level 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 з явними sibling-тестами в цих легких lanes, тож редагування helper не змушують повторно запускати повний важкий набір для цього каталогу. - - `auto-reply` тепер має три виділені bucket: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness reply з дешевих тестів status/chunk/token. -- Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context Compaction, + - Запускаються в CI + - Реальні ключі не потрібні + - Мають бути швидкими та стабільними +- Примітка щодо проєктів: + - Ненаправлений `pnpm test` тепер запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого нативного кореневого процесу проєкту. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension блокувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `vitest.config.ts`, оскільки multi-shard watch loop не є практичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup усе ще повертаються до широкого повторного запуску кореневого проєкту. + - `pnpm check:changed` — це звичайний smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни у public Plugin SDK і plugin-contract включають перевірку extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем версії верхнього рівня. + - Import-light unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper-вихідні файли `plugin-sdk` і `commands` також відображають changed-mode запуски на явні сусідні тести в цих light lanes, тому зміни helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі кошики: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. +- Примітка щодо embedded runner: + - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте в здоровому стані integration-набори embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. + - Також підтримуйте здоровий стан integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять + - Ці набори перевіряють, що scoped ids і поведінка Compaction усе ще проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих integration-шляхів. -- Примітка про pool: - - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live config. - - Коренева lane UI зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. + достатньою заміною цих integration-шляхів. +- Примітка щодо pool: + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у кореневих проєктах, конфігураціях e2e та live. + - Кореневий lane UI зберігає свої `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх процесів Node Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидкі локальні ітерації: + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти з типовою поведінкою V8. +- Примітка щодо швидких локальних ітерацій: - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після staged форматування/linting, тож core-only commits не сплачують ціну тестів extension, якщо не торкаються публічних контрактів, орієнтованих на extension. Commit, що зачіпають лише метадані релізу, лишаються на цільовій lane version/config/root-dependency. - - Якщо точний набір staged-змін уже був перевірений такими самими або сильнішими gates, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook. Staged format/lint усе одно запускаються. Згадайте завершені gates у своєму handoff. Це також прийнятно після повторного запуску ізольованого flaky hook failure, якщо він проходить із scoped proof. - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чітко зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автомасштабування локальних workers тепер навмисно консервативне і також знижує навантаження, коли середнє завантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням шкодять менше. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється тестове підключення. - - Конфігурація зберігає ввімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одне явне розташування кешу для прямого профілювання. -- Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітування про тривалість імпорту Vitest плюс вивід розкладу імпорту. - - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із нативним шляхом root-project для цього зафіксованого diff і виводить wall time плюс macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для накладних витрат запуску й трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим паралелізмом файлів. + - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тож core-only коміти не оплачують вартість тестів extension, якщо вони не торкаються public extension-facing контрактів. Коміти лише з release metadata залишаються на цільовому lane version/config/root-dependency. + - Якщо точний staged-набір змін уже був перевірений рівними або сильнішими gate, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook. Staged format/lint усе ще запускаються. Згадайте завершені gate у своєму handoff. Це також прийнятно після повторного запуску ізольованої flaky-помилки hook, яка успішно проходить із вузьким доказом. + - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чітко відображаються на менший набір. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом робочих процесів. + - Автомасштабування локальних робочих процесів тепер навмисно консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється обв’язка тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка щодо налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід розбивки імпорту. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд файлами, зміненими від `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з нативним шляхом кореневого проєкту для цього зафіксованого diff і виводить wall time плюс macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль основного потоку для накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap профілі раннера для unit-набору з вимкненим паралелізмом за файлами. ### Stability (Gateway) @@ -364,33 +364,33 @@ Compatibility aliases існують, щоб уникнути міграції - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Пропускає синтетичне churn повідомлень gateway, пам’яті й великих payload через шлях діагностичних подій - - Виконує запит до `diagnostics.stability` через Gateway WS RPC - - Охоплює допоміжні функції збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні RSS samples залишаються в межах бюджету тиску, а глибини черги для кожної сесії повертаються до нуля + - Проганяє синтетичне churn повідомлень Gateway, пам’яті та великих payload через шлях діагностичних подій + - Запитує `diagnostics.stability` через Gateway WS RPC + - Покриває helper збереження діагностичного stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні RSS-вибірки залишаються в межах бюджету тиску, а глибина черг на рівні сесії знову спадає до нуля - Очікування: - - Безпечно для CI й без ключів - - Вузька lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Безпечно для CI і без ключів + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (gateway smoke) +### E2E (Gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled plugin у `extensions/` - Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: типово 1). - - Типово запускається в silent mode, щоб зменшити накладні витрати на I/O консолі. + - Використовує адаптивну кількість worker (CI: до 2, локально: типово 1). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` — щоб примусово задати кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` — щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing Node і важчі мережеві сценарії + - Наскрізна поведінка multi-instance Gateway + - Поверхні WebSocket/HTTP, pairing Node і важче мережеве навантаження - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - - Не потребує реальних ключів - - Має більше рухомих частин, ніж unit-тести (може бути повільніше) + - Реальні ключі не потрібні + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) ### E2E: OpenShell backend smoke @@ -398,39 +398,39 @@ Compatibility aliases існують, щоб уникнути міграції - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile + - Створює sandbox з тимчасового локального Dockerfile - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox + - Перевіряє поведінку файлової системи remote-canonical через sandbox fs bridge - Очікування: - - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox + - Використовує ізольовані `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 script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Типове значення: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає rate limits - - Краще запускати звужені піднабори, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації до тимчасового тестового home, щоб unit-fixtures не могли змінювати ваш реальний `~/.openclaw`. + - За задумом не є CI-стабільними (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштують грошей / використовують rate limits + - Краще запускати звужені підмножини, а не «все» +- Live-запуски підтягують `~/.profile`, щоб отримати відсутні API keys. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації в тимчасовий тестовий 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. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує bootstrap-логи Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup-логи. +- Ротація API keys (залежно від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення per-live через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу при відповідях rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було помітно навіть тоді, коли перехоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway транслюються негайно під час live-запусків. - - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера помітно показували активність навіть тоді, коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/Gateway транслюються одразу під час live-запусків. + - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? @@ -438,119 +438,119 @@ Compatibility aliases існують, щоб уникнути міграції Використовуйте цю таблицю рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтесь мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклик інструментів: запускайте звужений `pnpm test:live` +- Торкаєтесь мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android Node +## Live: обхід можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз рекламує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яку зараз рекламує** під’єднаний Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Ручне/попередньо підготовлене налаштування (набір не встановлює/не запускає/не pair-ить застосунок). + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pairing застосунку). - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. -- Необхідна попередня підготовка: - - Android-застосунок уже підключено й pair-ено до Gateway. - - Застосунок має залишатися на передньому плані. - - Для можливостей, які мають проходити, надано дозволи/згоду на захоплення. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже під’єднано та спарено з Gateway. + - Застосунок утримується на передньому плані. + - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте успішно перевірити. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: перевірка моделей (ключі профілів) +## Live: smoke моделей (ключі профілів) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділені на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює для цієї моделі повний pipeline gateway+agent (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» каже нам, чи провайдер/модель узагалі можуть відповісти з наданим ключем. +- «Gateway smoke» каже нам, чи працює повний конвеєр Gateway+агента для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). ### Шар 1: Пряме завершення моделі (без Gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике завершення для кожної моделі (і цільові регресії там, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на Gateway smoke +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався сфокусованим на Gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Modern/all-перевірки за замовчуванням мають curated high-signal обмеження; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. + - Modern/all-обходи типово обмежені добіркою з високим сигналом; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-обходу або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і запасні варіанти з env - - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: profile store і резервні env-джерела + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відділяє «API провайдера зламаний / ключ недійсний» від «pipeline Gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: повторення reasoning replay + потоки tool-call для OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр агента Gateway зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: Gateway + smoke dev agent (те, що насправді робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (те, що фактично робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process Gateway - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі з ключами й перевірити: + - Ітерувати моделі-з-ключами та перевіряти: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (probe читання) - - необов’язкові додаткові probe інструментів (probe exec+read) - - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probe (щоб ви могли швидко пояснювати збої): - - probe `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - probe `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його через `read`. - - probe зображення: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - що реальний виклик інструмента працює (read probe) + - необов’язкові додаткові перевірки інструментів (exec+read probe) + - що регресійні шляхи OpenAI (лише tool-call → подальший крок) і далі працюють +- Деталі probe (щоб можна було швидко пояснити збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. + - `exec+read` probe: тест просить агента `exec`-записати nonce у тимчасовий файл, а потім `read` його назад. + - image probe: тест додає згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити - - Modern/all-перевірки Gateway за замовчуванням мають curated high-signal обмеження; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникати «всього OpenRouter»): + - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Modern/all gateway-обходи типово обмежені добіркою з високим сигналом; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-обходу або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникнути «все підряд через OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Probe інструментів + зображень у цьому live-тесті завжди ввімкнені: - - probe `read` + probe `exec+read` (навантаження на інструменти) - - probe зображення запускається, коли модель рекламує підтримку введення зображень +- Перевірки tool + image у цьому live-тесті завжди увімкнені: + - `read` probe + `exec+read` probe (навантаження на інструменти) + - image probe запускається, коли модель оголошує підтримку image input - Потік (на високому рівні): - Тест генерує крихітний 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`) - - Вбудований агент пересилає мультимодальне повідомлення користувача моделі + - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає моделі мультимодальне повідомлення користувача - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете протестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI-backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent з використанням локального CLI backend, не торкаючись вашої типової конфігурації. -- Типові значення smoke для конкретних backend зберігаються у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити конвеєр Gateway + агента з використанням локального CLI-backend, не торкаючись вашої типової конфігурації. +- Типові значення smoke для конкретного backend живуть у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Команда/аргументи/поведінка зображення беруться з метаданих plugin CLI backend-власника. + - Поведінка command/args/image береться з метаданих plugin-власника CLI-backend. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення зображення (шляхи ін’єктуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість ін’єкції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням аргументів зображення, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову probe безперервності тієї самої сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї ж сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово увімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -560,13 +560,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -577,29 +577,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає smoke CLI-backend live усередині Docker image репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища API key Anthropic. Ця lane підписки типово вимикає probe Claude MCP/tool і probe зображень, тому що Claude зараз маршрутизує використання сторонніх застосунків через додаткове тарифікування usage замість звичайних лімітів тарифного плану підписки. -- Smoke CLI-backend live тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI Gateway. -- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розміщено в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносимого Claude Code subscription OAuth через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних Anthropic API key. Цей шлях subscription типово вимикає перевірки Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий наскрізний потік для 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` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: +- Мета: перевірити реальний потік conversation-bind ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє до транскрипту прив’язаної ACP-сесії + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайний follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст розмови у стилі Slack DM - - ACP backend: `acpx` + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` + - Синтетичний канал: контекст conversation у стилі Slack DM + - ACP-backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -608,8 +608,8 @@ 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.4` - Примітки: - - Ця lane використовує поверхню `chat.send` Gateway з синтетичними полями originating-route, доступними лише адміністратору, щоб тести могли приєднувати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent plugin `acpx` для вибраного ACP harness agent. + - Цей lane використовує поверхню Gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли додавати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -619,13 +619,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent: +Docker-рецепти для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -635,35 +635,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він послідовно запускає smoke ACP bind для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. -- Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити matrix. -- Він використовує `~/.profile`, розміщує відповідні матеріали CLI auth у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав змінні середовища провайдера із завантаженого профілю доступними для дочірнього harness CLI. +- Docker-ранер розміщено в `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. +- Він підтягує `~/.profile`, переносить відповідні матеріали CLI auth у контейнер, встановлює `acpx` у записуваний npm-префікс, а потім за потреби встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підвантаженого профілю доступними для дочірнього CLI harness. ## Live: smoke Codex app-server harness -- Мета: перевірити harness Codex, що належить plugin, через звичайний метод Gateway +- Мета: перевірити plugin-власний harness Codex через звичайний Gateway-метод `agent`: - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread app-server - може відновитися - - запустити `/codex status` і `/codex models` через той самий командний - шлях gateway - - за бажанням виконати дві перевірки shell із підвищеними правами, переглянуті Guardian: одну нешкідливу - команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути - відхилене, щоб agent перепитав + - надіслати перший хід Gateway agent до `codex/gpt-5.4` + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що app-server + thread може відновитися + - виконати `/codex status` і `/codex models` через той самий командний шлях + Gateway + - необов’язково виконати дві escalated shell-probes, перевірені Guardian: одну нешкідливу + команду, яку слід схвалити, і одне фіктивне завантаження секрету, яке слід + відхилити, щоб агент поставив уточнювальне запитання - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язкова probe зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова probe MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язкова probe Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, тож зламаний harness Codex - не зможе пройти, непомітно переключившись назад на Pi. -- Auth: `OPENAI_API_KEY` із shell/profile, а також за бажанням скопійовані +- Необов’язкова 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: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -678,7 +678,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash source ~/.profile @@ -687,24 +687,21 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - auth CLI Codex, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- - префікс, розміщує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням увімкнює probe зображення, MCP/tool і Guardian. Встановіть +- Docker-ранер розміщено в `scripts/test-live-codex-harness-docker.sh`. +- Він підтягує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm + префікс, переносить вихідне дерево, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає image-, MCP/tool- і Guardian-probes. Встановіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний - запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live- - тесту, тож fallback до `openai-codex/*` або Pi не може приховати регресію - Codex harness. + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, щоб `openai-codex/*` або відкат на PI не могли приховати регресію Codex harness. ### Рекомендовані live-рецепти -Найшвидшими й найменш нестабільними є вузькі, явні allowlist: +Вузькі явні allowlist — найшвидші й найменш нестабільні: -- Одна модель, напряму (без Gateway): +- Одна модель, direct (без Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, Gateway smoke: @@ -720,21 +717,21 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). +- `google-antigravity/...` використовує міст OAuth Antigravity (ендпойнт агента в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Google Gemini API через HTTP (API key / auth профілю); саме це більшість користувачів має на увазі під “Gemini”. - - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну auth і може поводитися інакше (streaming/підтримка інструментів/розходження версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує shell-виклик локального двійкового файла `gemini`; він має власну auth і може поводитися інакше (streaming/підтримка інструментів/розходження версій). -## Live: matrix моделей (що ми охоплюємо) +## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live запускається за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live — це opt-in), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний набір 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: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -742,12 +739,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустіть Gateway smoke з інструментами + зображенням: +Запуск smoke Gateway з інструментами + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Вибирайте щонайменше одну модель на кожну родину провайдерів: +Оберіть принаймні одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -758,59 +755,59 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою інструментів, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо маєте доступ) +- Mistral: `mistral/`… (оберіть одну модель із підтримкою інструментів, яку у вас увімкнено) +- Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити probe зображення. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. -### Aggregators / альтернативні Gateway +### Агрегатори / альтернативні Gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою інструментів і зображень) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live matrix (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, яких можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoints): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні ендпойнти): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко прописувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) -Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «profile keys») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги CLI auth до тимчасового тестового home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального робочого простору хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в staging live-home, якщо існує, але це не основне сховище profile keys) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги CLI auth у тимчасовий тестовий home; staged live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального host-workspace. -Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.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 coding plan - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## 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` - Обсяг: - - Перевіряє bundled шляхи зображень, відео та `music_generate` у comfy + - Перевіряє вбудовані шляхи comfy image, video і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin @@ -820,16 +817,16 @@ Live-тести виявляють облікові дані так само, я - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API keys раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: + - Перелічує кожен зареєстрований provider plugin для генерації зображень + - Завантажує відсутні env-змінні провайдерів з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled провайдери, які охоплюються: +- Поточні bundled providers, що покриваються: - `fal` - `google` - `minimax` @@ -841,7 +838,7 @@ Live-тести виявляють облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Live генерація музики @@ -849,23 +846,23 @@ Live-тести виявляють облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний bundled-шлях провайдерів генерації музики - - Наразі охоплює Google і MiniMax - - Завантажує env vars провайдера з вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API keys раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з введенням лише prompt + - Перевіряє спільний bundled-шлях provider для генерації музики + - Наразі покриває Google і MiniMax + - Завантажує env-змінні провайдерів з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Запускає обидва оголошені режими runtime, коли вони доступні: + - `generate` з вхідними даними лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної lane: + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, не цей спільний обхід - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Live генерація відео @@ -873,257 +870,257 @@ Live-тести виявляють облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний bundled-шлях провайдерів генерації відео - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери, крім FAL, один запит text-to-video на провайдера, prompt про лобстера на одну секунду й обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - Типово пропускає FAL, тому що затримка черги на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env vars провайдера з вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API keys раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної auth/profile/model + - Перевіряє спільний bundled-шлях provider для генерації відео + - За замовчуванням використовує smoke-шлях, безпечний для релізу: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt про омара та ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - Типово пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдерів з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model - За замовчуванням запускає лише `generate` - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі buffer у спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі buffer у спільній перевірці - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільній перевірці: - - `vydra`, тому що bundled `veo3` є лише текстовим, а bundled `kling` потребує віддаленого URL зображення - - Покриття Vydra, специфічне для провайдера: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні дані зображення на основі buffer у спільному обході + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні дані відео на основі buffer у спільному обході + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному обході: + - `vydra`, тому що bundled `veo3` підтримує лише текст, а bundled `kling` вимагає віддалений URL-адрес зображення + - Покриття Vydra для конкретного провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка за замовчуванням використовує fixture віддаленого URL зображення + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує фікстуру з віддаленим URL-адресом зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільній перевірці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз потребують віддалених еталонних URL `http(s)` / MP4 - - `google`, тому що поточна спільна lane Gemini/Veo використовує локальне введення на основі buffer, а цей шлях не приймається в спільній перевірці - - `openai`, тому що поточна спільна lane не гарантує доступ до org-специфічного video inpaint/remix + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному обході: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалених URL-адрес `http(s)` / MP4 reference + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається в спільному обході + - `openai`, тому що поточний спільний lane не гарантує організаційно-специфічний доступ до video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового обходу, включно з FAL + - `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 для live-медіа - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори зображень, музики й відео через одну нативну для репозиторію entrypoint - - Автоматично завантажує відсутні env vars провайдера з `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які зараз мають придатну auth - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори image, music і video через один нативний entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатні auth + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker runners (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві категорії: +Ці Docker-ранери поділяються на дві групи: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл ключів профілю всередині Docker image репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог конфігурації та workspace (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням мають менший smoke-ліміт, щоб повна 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`), монтуючи ваш локальний каталог конфігурації та workspace (і підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke-ліміт, щоб повний Docker-обхід залишався практичним: `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - явно хочете більшу вичерпну перевірку. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lane live. Він також збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke runners E2E, які перевіряють зібраний застосунок. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам явно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker-lanes. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для smoke-ранерів E2E у контейнерах, які перевіряють зібраний застосунок. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker runners для live-model також bind-mount лише потрібні home-каталоги CLI auth (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home-каталог контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи сховище auth на хості: +Docker-ранери live-моделей також bind-монтують лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище auth на хості: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) - Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke Codex app-server harness: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер onboarding (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding env-ref плюс Telegram за замовчуванням, перевіряє, що ввімкнення plugin встановлює його runtime deps на вимогу, запускає doctor і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Мережевий Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово викликає відхилення схеми провайдера й перевіряє, що сира деталь з’являється в логах Gateway. -- MCP channel bridge (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP для пакета Pi (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків Cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика restart для пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з посиланням на env, а також типово Telegram, перевіряє, що ввімкнення plugin встановлює його runtime deps за потреби, запускає doctor і виконує один mock-хід агента OpenAI. Повторно використовуйте заздалегідь зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Мережева взаємодія 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`) запускає mock-сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення схеми провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. +- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP-сервер + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Cleanup Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Smoke незмінності оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) - Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Під час ітерацій звужуйте runtime deps bundled plugin, вимикаючи не пов’язані сценарії, наприклад: +- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий образ Docker-ранера, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте runtime deps bundled plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використати спільний built-app image: +Щоб вручну попередньо зібрати й повторно використовувати спільний 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, скрипти виконують його pull, якщо його ще немає локально. Docker-тести QR та встановлювача зберігають власні Dockerfiles, тому що вони перевіряють поведінку пакування/встановлення, а не спільний runtime зібраного застосунку. +Перевизначення образу для конкретного набору, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. -Docker runners для live-model також bind-mount поточний checkout лише для читання і -розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно запускає Vitest проти точно вашого локального source/config. -Крок розміщення пропускає великі локальні кеші та результати збирання застосунків, такі -як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +Docker-ранери live-моделей також bind-монтують поточний checkout лише для читання та +переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, але все одно запускає Vitest точно на вашому локальному source/config. +Крок staging пропускає великі локальні кеші та результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes Gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. +реальні воркери каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття Gateway -з цієї Docker lane. +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття Gateway +live у цьому Docker-lane. `test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoints, -запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через proxy `/api/chat/completions` в Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити -image Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. -Ця lane очікує придатний ключ live model, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, +запускає контейнер Open WebUI із закріпленою версією проти цього Gateway, входить +через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити +образ Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб передати його в Dockerized-запусках. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded container -Gateway, запускає другий контейнер, який створює `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення про channel + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тож smoke перевіряє те, що bridge -справді видає, а не лише те, що вдається показати конкретному клієнтському SDK. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live -model. Він збирає Docker image репозиторію, запускає всередині контейнера реальний stdio MCP probe server, -матеріалізує цей server через вбудований runtime MCP пакета Pi, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway +container, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих conversation, читання transcript, metadata вкладень, +поведінку черги live-подій, маршрутизацію outbound send і сповіщення каналів + +дозволів у стилі Claude через реальний міст stdio MCP. Перевірка сповіщень +напряму аналізує сирі кадри stdio MCP, тож smoke перевіряє те, що міст +справді надсилає, а не лише те, що випадково відображає конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live-моделі. +Він збирає Docker-образ репозиторію, запускає реальний сервер stdio MCP probe +усередині контейнера, матеріалізує цей сервер через вбудований runtime Pi bundle +MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live model. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним сервером stdio MCP probe, виконує +ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke plain-language thread ACP (не CI): +Ручна smoke-перевірка ACP plain-language thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації потоків ACP, тому не видаляйте його. +- Зберігайте цей скрипт для workflow регресій/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні env vars: +Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, отримані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підтягується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після змін у документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку прив’язок Mintlify, коли також потрібні перевірки заголовків усередині сторінок: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки: `pnpm check:docs`. +Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібна перевірка заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) -Це регресії «реального pipeline» без реальних провайдерів: +Це регресії «реального конвеєра» без реальних провайдерів: -- Виклик інструментів Gateway (змоканий 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, реальний цикл Gateway + агента): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Evals надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька CI-safe тестів, які поводяться як «evals надійності агента»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний цикл Gateway + агента (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, що перевіряють обв’язку сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що для Skills ще бракує (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає agent `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічені в prompt, чи обирає агент правильний Skill (або уникає нерелевантних)? +- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Workflow contracts:** багатоходові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають насамперед лишатися детермінованими: +Майбутні evals мають насамперед залишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. -- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, gating, ін’єкція в prompt). -- Необов’язкові live-оцінювання (за явним увімкненням, керовані env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв з mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і обв’язки сесій. +- Невеликий набір сценаріїв, орієнтованих на skills (використати чи уникнути, gate, prompt injection). +- Необов’язкові live evals (opt-in, керовані env) — лише після того, як буде готовий CI-safe набір. ## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму інтерфейсному контракту. Вони перебирають усі виявлені plugins і запускають +набір перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +коли торкаєтесь спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти каналів: `pnpm test:contracts:channels` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` -### Контракти channel +### Контракти каналів Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування +- **setup** - Контракт майстра setup - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій channel -- **threading** - Обробка ID потоків -- **directory** - API каталогу/складу -- **group-policy** - Застосування групової політики +- **actions** - Обробники дій каналу +- **threading** - Обробка ID thread +- **directory** - API каталогу/реєстру +- **group-policy** - Застосування group policy -### Контракти status provider +### Контракти стану провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки status channel +- **status** - Перевірки стану каналу - **registry** - Форма реєстру plugin -### Контракти provider +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/selection auth +- **auth-choice** - Вибір/відбір auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin -- **runtime** - Runtime provider +- **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер налаштування +- **wizard** - Майстер setup ### Коли запускати - Після зміни експортів або підшляхів plugin-sdk -- Після додавання або зміни plugin каналу чи провайдера +- Після додавання або зміни channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin Контрактні тести запускаються в CI і не потребують реальних API keys. -## Додавання регресій (настанови) +## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або фіксацію точної трансформації форми запиту) -- Якщо вона за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і таким, що вмикається через env vars -- Віддавайте перевагу найменшому шару, який ловить баг: - - баг перетворення/повторення запиту provider → direct models test - - баг pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI gateway mock test -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було мовчки пропустити. +- Якщо можливо, додайте регресію, безпечну для CI (mock/stub провайдер або захоплення точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу націлюванню на найменший шар, який виявляє помилку: + - помилка перетворення/відтворення запиту провайдера → direct models test + - помилка конвеєра сесії/історії/інструментів Gateway → Gateway live smoke або безпечний для CI mock-тест Gateway +- Guardrail обходу 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, щоб нові класи не можна було тихо пропустити.