diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index 00c1d7373..d51c3773d 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -3,13 +3,13 @@ read_when: - Розширення qa-lab або qa-channel - Додавання сценаріїв QA з підтримкою репозиторію - Побудова більш реалістичної автоматизації QA навколо панелі керування Gateway -summary: Приватна структура автоматизації QA для qa-lab, qa-channel, попередньо підготовлених сценаріїв і звітів протоколу +summary: Приватна форма автоматизації QA для qa-lab, qa-channel, сценаріїв із початковими даними та звітів протоколу title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-17T15:05:27Z" + generated_at: "2026-04-20T02:15:03Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- @@ -17,33 +17,33 @@ x-i18n: # Автоматизація QA E2E Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, -орієнтований на канали спосіб, ніж це може зробити один модульний тест. +каналоподібний спосіб, ніж це може зробити один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, потоку, - реакцій, редагування та видалення. -- `extensions/qa-lab`: UI налагодження та QA bus для спостереження за транскриптом, - ін’єкції вхідних повідомлень і експорту 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 транскрипт і план сценарію. +- Праворуч: QA Lab, де показано транскрипт у стилі Slack та план сценарію. -Запустіть це так: +Запустіть його так: ```bash pnpm qa:lab:up ``` -Це збирає сайт QA, запускає lane Gateway на основі Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту -QA-місію, спостерігати реальну поведінку каналу та фіксувати, що спрацювало, -що не спрацювало або що лишилося заблокованим. +Це збирає сайт QA, запускає лінію Gateway на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, +спостерігати реальну поведінку каналу та записувати, що спрацювало, що не спрацювало або +що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без повторної збірки Docker-образу щоразу +Для швидшої ітерації UI QA Lab без повторного збирання Docker-образу щоразу запустіть стек із bind-mounted збіркою QA Lab: ```bash @@ -53,80 +53,79 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` залишає сервіси Docker на попередньо зібраному образі та bind-mount’ить +`qa:lab:up:fast` залишає Docker-сервіси на попередньо зібраному образі та bind-mount-ить `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, -коли змінюється хеш ресурсів QA Lab. +перезбирає цю збірку при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. -Для Matrix smoke lane з реальним транспортом запустіть: +Для транспортно-реалістичної лінії smoke для Matrix виконайте: ```bash pnpm openclaw qa matrix ``` -Цей lane розгортає в Docker одноразовий homeserver Tuwunel, реєструє -тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, -а потім запускає справжній Matrix Plugin у дочірньому QA Gateway. Lane з живим -транспортом зберігає конфігурацію дочірнього процесу обмеженою транспортом, -що тестується, тому Matrix запускається без `qa-channel` у дочірній конфігурації. -Він записує структуровані артефакти звіту та об’єднаний журнал stdout/stderr -у вибраний вихідний каталог Matrix QA. Щоб також зафіксувати зовнішній вивід -збірки/запуску `scripts/run-node.mjs`, встановіть -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` у файл журналу всередині репозиторію. +Ця лінія розгортає одноразовий homeserver Tuwunel у Docker, реєструє +тимчасових користувачів driver, SUT та observer, створює одну приватну кімнату, а потім запускає +реальний Plugin Matrix усередині дочірнього процесу QA gateway. Лінія живого транспорту залишає +конфігурацію дочірнього процесу обмеженою транспортом, що тестується, тож Matrix працює без +`qa-channel` у конфігурації дочірнього процесу. Вона записує структуровані артефакти звіту та +обʼєднаний журнал stdout/stderr у вибраний каталог виводу Matrix QA. Щоб +також захопити зовнішній вивід збірки/запуску `scripts/run-node.mjs`, установіть +`OPENCLAW_RUN_NODE_OUTPUT_LOG=` на файл журналу всередині репозиторію. -Для Telegram smoke lane з реальним транспортом запустіть: +Для транспортно-реалістичної лінії smoke для Telegram виконайте: ```bash pnpm openclaw qa telegram ``` -Цей lane працює з однією реальною приватною групою Telegram замість -розгортання одноразового сервера. Він потребує -`OPENCLAW_QA_TELEGRAM_GROUP_ID`, +Ця лінія націлюється на одну реальну приватну групу Telegram замість розгортання +одноразового сервера. Вона вимагає `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також двох різних ботів в одній -приватній групі. Бот SUT повинен мати ім’я користувача Telegram, а -спостереження бот-до-бота працює найкраще, коли в обох ботів увімкнено -Bot-to-Bot Communication Mode у `@BotFather`. +приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а спостереження бот-до-бота +працює найкраще, коли в обох ботів увімкнено Bot-to-Bot Communication Mode +у `@BotFather`. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо +вам потрібні артефакти без коду завершення з помилкою. -Lane з живим транспортом тепер використовують один менший контракт замість -того, щоб кожен вигадував власну форму списку сценаріїв: +Тепер лінії живого транспорту мають один спільний менший контракт замість того, щоб кожна +вигадувала власну форму списку сценаріїв: -`qa-channel` лишається широким набором перевірок поведінки продукту із -синтетичним середовищем і не входить до матриці покриття живого транспорту. +`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту і не входить +до матриці покриття живого транспорту. -| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у потоці | Ізоляція потоку | Спостереження реакцій | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | --------------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в треді | Ізоляція треду | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix, -Telegram і майбутні живі транспорти спільно використовують один явний контрольний список -транспортного контракту. +Telegram та майбутні живі транспорти мають один явний контрольний список транспортного контракту. -Для одноразового lane на Linux VM без використання Docker у шляху QA запустіть: +Для одноразової лінії Linux VM без залучення Docker до шляху QA виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` Це завантажує нову гостьову систему Multipass, встановлює залежності, збирає OpenClaw -всередині гостя, запускає `qa suite`, а потім копіює звичайний QA-звіт і +усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт QA та підсумок назад у `.artifacts/qa-e2e/...` на хості. -Використовується така сама поведінка вибору сценаріїв, як і для `qa suite` на хості. -Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних -сценаріїв паралельно з ізольованими працівниками Gateway — до 64 працівників -або до кількості вибраних сценаріїв. Використовуйте `--concurrency ` для -налаштування кількості працівників або `--concurrency 1` для послідовного виконання. -Живі запуски передають підтримувані вхідні дані автентифікації QA, які практично -можна використовувати в гостьовій системі: ключі провайдерів через env, -шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. -Тримайте `--output-dir` у межах кореня репозиторію, щоб гість -міг записувати результати назад через змонтований workspace. +Вона повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. +Запуски suite на хості й у Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно +з ізольованими воркерами gateway. `qa-channel` за замовчуванням має concurrency 4, +обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати +кількість воркерів, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо +вам потрібні артефакти без коду завершення з помилкою. +Живі запуски пересилають підтримувані вхідні дані автентифікації QA, які практично +використовувати в гостьовій системі: ключі провайдера через env, шлях до конфігурації живого провайдера QA і +`CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість +міг записувати дані назад через змонтований workspace. ## Початкові дані з підтримкою репозиторію -Ресурси початкових даних зберігаються в `qa/`: +Ресурси з початковими даними зберігаються в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` @@ -135,81 +134,78 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline агенту. `qa-lab` має залишатися загальним виконавцем markdown. Кожен markdown-файл сценарію є -джерелом істини для одного тестового запуску і повинен визначати: +джерелом істини для одного тестового запуску та має визначати: - метадані сценарію -- необов’язкові метадані категорії, можливостей, lane і ризику -- посилання на документацію та код -- необов’язкові вимоги до Plugin -- необов’язковий patch конфігурації Gateway +- необовʼязкові метадані категорії, можливості, лінії та ризику +- посилання на docs і код +- необовʼязкові вимоги до Plugin +- необовʼязковий patch конфігурації gateway - виконуваний `qa-flow` -Багаторазово використовувана поверхня середовища виконання, що лежить в основі `qa-flow`, -може залишатися загальною та наскрізною. Наприклад, markdown-сценарії можуть -поєднувати helpers на стороні транспорту з helpers на стороні браузера, які керують -вбудованим Control UI через шов Gateway `browser.request`, не додаючи -спеціального виконавця для окремих випадків. +Багаторазова поверхня виконання, яка лежить в основі `qa-flow`, може залишатися загальною +і кросфункціональною. Наприклад, markdown-сценарії можуть поєднувати допоміжні засоби +з боку транспорту з допоміжними засобами з боку браузера, які керують вбудованим Control UI через +поверхню Gateway `browser.request`, не додаючи спеціалізованого виконавця. Файли сценаріїв слід групувати за можливостями продукту, а не за папкою дерева -вихідного коду. Зберігайте стабільність ідентифікаторів сценаріїв при переміщенні файлів; -використовуйте `docsRefs` і `codeRefs` для трасування реалізації. +вихідного коду. Зберігайте ідентифікатори сценаріїв стабільними, коли файли переміщуються; використовуйте `docsRefs` і `codeRefs` +для трасування реалізації. -Базовий список має залишатися достатньо широким, щоб покривати: +Базовий список має залишатися достатньо широким, щоб охоплювати: -- DM і чат каналу -- поведінку потоку +- чат у DM і каналі +- поведінку тредів - життєвий цикл дій із повідомленнями - зворотні виклики Cron -- відновлення з пам’яті +- виклик памʼяті - перемикання моделей - передавання підзадачі субагенту -- читання репозиторію та документації -- одне невелике завдання зі збірки, наприклад Lobster Invaders +- читання репозиторію та docs +- одне невелике завдання зі збирання, наприклад Lobster Invaders -## Mock lanes провайдерів +## Лінії mock провайдерів -`qa suite` має два локальні mock lanes провайдерів: +`qa suite` має дві локальні лінії mock провайдерів: -- `mock-openai` — це сценарійно-орієнтований mock OpenClaw. Він лишається типовим - детерміністичним mock lane для QA з підтримкою репозиторію та перевірок паритету. -- `aimock` запускає сервер провайдера на основі AIMock для експериментального - покриття протоколу, фікстур, record/replay і chaos. Це доповнення, яке не - замінює диспетчер сценаріїв `mock-openai`. +- `mock-openai` — це сценарійно-орієнтований mock OpenClaw. Він залишається типовою + детермінованою лінією mock для QA з підтримкою репозиторію та перевірок паритету. +- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколу, + фікстур, record/replay та chaos. Це доповнення, а не заміна диспетчера сценаріїв `mock-openai`. -Реалізація provider-lane розташована в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, -конфігурацією моделі Gateway, потребами staging для auth-profile, а також -прапорами можливостей live/mock. Спільний код suite і Gateway повинен -маршрутизуватися через реєстр провайдерів, а не розгалужуватися за назвами провайдерів. +Реалізація ліній провайдерів розміщена в `extensions/qa-lab/src/providers/`. +Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделей gateway, +потребами підготовки профілів автентифікації та прапорцями можливостей live/mock. Спільний код suite і +gateway має маршрутизувати через реєстр провайдерів замість розгалуження за назвами провайдерів. ## Адаптери транспорту -`qa-lab` володіє загальним транспортним швом для markdown-сценаріїв QA. -`qa-channel` — перший адаптер на цьому шві, але ціль дизайну ширша: -майбутні реальні або синтетичні канали повинні підключатися до того самого -виконавця suite замість додавання transport-specific виконавця QA. +`qa-lab` володіє загальною транспортною поверхнею для markdown-сценаріїв QA. +`qa-channel` — перший адаптер на цій поверхні, але ціль дизайну ширша: +майбутні реальні або синтетичні канали мають підключатися до того самого виконавця suite +замість додавання виконавця QA, специфічного для транспорту. -На рівні архітектури розділення таке: +На рівні архітектури розподіл такий: -- `qa-lab` володіє загальним виконанням сценаріїв, паралелізмом працівників, записом артефактів і звітністю. -- адаптер транспорту володіє конфігурацією Gateway, готовністю, спостереженням за вхідними та вихідними подіями, транспортними діями та нормалізованим станом транспорту. -- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазово використовувану поверхню середовища виконання, яка його виконує. +- `qa-lab` володіє загальним виконанням сценаріїв, паралельністю воркерів, записом артефактів і звітністю. +- адаптер транспорту володіє конфігурацією gateway, готовністю, спостереженням за вхідними та вихідними подіями, транспортними діями та нормалізованим станом транспорту. +- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову поверхню виконання, яка його виконує. -Рекомендації для мейнтейнерів щодо підключення нових адаптерів каналів розміщені в +Орієнтовані на мейнтейнерів вказівки з упровадження нових адаптерів каналів розміщені в [Testing](/uk/help/testing#adding-a-channel-to-qa). ## Звітність -`qa-lab` експортує Markdown-звіт протоколу на основі спостережуваної часової шкали bus. +`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. Звіт має відповідати на запитання: - Що спрацювало - Що не спрацювало -- Що лишилося заблокованим -- Які додаткові сценарії варто додати +- Що залишилося заблокованим +- Які подальші сценарії варто додати -Для перевірок характеру та стилю запустіть той самий сценарій на кількох live model -refs і запишіть оцінений Markdown-звіт: +Для перевірок характеру й стилю запустіть той самий сценарій для кількох живих ref моделей +і запишіть оцінений Markdown-звіт: ```bash pnpm openclaw qa character-eval \ @@ -228,43 +224,39 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси QA Gateway, а не Docker. Сценарії -оцінювання характеру повинні задавати persona через `SOUL.md`, а потім виконувати -звичайні користувацькі ходи, такі як чат, допомога з workspace і невеликі -завдання з файлами. Моделі-кандидату не слід повідомляти, що її оцінюють. -Команда зберігає кожен повний транскрипт, записує базову статистику запуску, -а потім просить judge models у fast mode з reasoning `xhigh` -ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` при порівнянні провайдерів: -prompt для judge, як і раніше, отримує кожен транскрипт і статус запуску, -але refs кандидатів замінюються нейтральними мітками, такими як `candidate-01`; -після парсингу звіт зіставляє рейтинги назад із реальними refs. -Для кандидатів за замовчуванням використовується thinking `high`, а для моделей OpenAI, -які це підтримують, — `xhigh`. Перевизначте конкретного кандидата безпосередньо через -`--model provider/model,thinking=`. `--thinking ` як і раніше задає -глобальне резервне значення, а старіша форма `--model-thinking ` -збережена для сумісності. -Refs кандидатів OpenAI за замовчуванням використовують fast mode, щоб там, де -це підтримується провайдером, застосовувалася пріоритетна обробка. Додайте `,fast`, -`,no-fast` або `,fast=false` безпосередньо в рядку, якщо для окремого кандидата -або judge потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість запусків -кандидатів і judge також записується у звіт для аналізу бенчмарків, але prompts для -judge явно вказують не ранжувати за швидкістю. -Запуски моделей-кандидатів і judge за замовчуванням виконуються з concurrency 16. -Зменшуйте `--concurrency` або `--judge-concurrency`, коли обмеження провайдера або -навантаження локального Gateway роблять запуск занадто шумним. -Якщо не передано жодного кандидатського `--model`, character eval за замовчуванням -використовує +Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії оцінювання характеру +мають задавати persona через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, +такі як чат, допомога з workspace та невеликі файлові завдання. Моделі-кандидату +не слід повідомляти, що її оцінюють. Команда зберігає кожен повний +транскрипт, записує базову статистику запуску, а потім просить моделі-суддів у швидкому режимі з +міркуванням `xhigh` ранжувати запуски за природністю, вайбом і гумором. +Використовуйте `--blind-judge-models` при порівнянні провайдерів: підказка для суддів усе одно отримує +кожен транскрипт і статус запуску, але ref кандидатів замінюються на нейтральні +мітки, такі як `candidate-01`; після парсингу звіт зіставляє рейтинги назад із реальними ref. +Запуски кандидатів за замовчуванням використовують рівень мислення `high`, а для моделей OpenAI, які це підтримують, — `xhigh`. +Щоб перевизначити конкретного кандидата, використовуйте inline-форму +`--model provider/model,thinking=`. `--thinking ` і надалі задає +глобальне резервне значення, а старіша форма `--model-thinking ` зберігається +для сумісності. +ref кандидатів OpenAI за замовчуванням працюють у швидкому режимі, щоб використовувати пріоритетну обробку там, +де це підтримується провайдером. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли +одному кандидату або судді потрібно перевизначення. Передавайте `--fast`, лише якщо хочете +примусово ввімкнути швидкий режим для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +записується у звіт для аналізу продуктивності, але підказки для суддів прямо кажуть +не ранжувати за швидкістю. +Запуски моделей-кандидатів і моделей-суддів за замовчуванням обидва використовують concurrency 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, коли ліміти провайдера чи навантаження на локальний gateway +роблять запуск надто шумним. +Коли не передано жодного кандидата `--model`, character eval за замовчуванням використовує `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і `google/gemini-3.1-pro-preview`, якщо не передано `--model`. -Якщо не передано жодного `--judge-model`, judges за замовчуванням: +Коли не передано `--judge-model`, за замовчуванням як судді використовуються `openai/gpt-5.4,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. -## Пов’язана документація +## Повʼязані docs - [Testing](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 18aa012a6..534067f28 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,106 +1,108 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/провайдерів + - Додавання регресійних тестів для помилок моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-раннери та що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-17T15:05:35Z" + generated_at: "2026-04-20T02:15:05Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-раннерів. -Цей документ — посібник «як ми тестуємо»: +Цей документ — це посібник «як ми тестуємо»: -- Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Що покриває кожен набір (і що він навмисно _не_ покриває) +- Які команди запускати для поширених сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресійні тести для реальних проблем моделі/провайдера ## Швидкий старт У більшості випадків: -- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` +- Повна перевірка (очікується перед push): `pnpm build && pnpm check && 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-канал на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете мати додаткову впевненість: -- Gate покриття: `pnpm test:coverage` +- Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Набір live (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## Спеціальні QA-раннери -Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. - - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway, до 64 воркерів або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної гілки. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами gateway. Для `qa-channel` типовий рівень паралелізму — 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішого послідовного режиму. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає помилки. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття фікстур і моків протоколу без заміни гілки `mock-openai`, орієнтованої на сценарії. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття фікстур і протокольних моків без заміни сценарно-орієнтованого режиму `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині одноразової Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Multipass Linux VM. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA-входи автентифікації, які практичні для гостьової системи: - ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. + - Live-запуски передають підтримувані QA-входи автентифікації, практичні для гостьової системи: + ключі провайдера через env, шлях конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у + - Записує звичайний QA-звіт + підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для операторської QA-роботи. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-гілку Matrix проти одноразового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані інсталяції OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Копії репозиторію завантажують вбудований раннер безпосередньо; окремий крок встановлення 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 не надає спільні прапорці джерела облікових даних, оскільки гілка локально створює одноразових користувачів. - - Записує звіт Matrix QA, підсумок, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає Matrix live QA-канал проти тимчасового Docker-backed сервера Tuwunel homeserver. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні інсталяції OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. + - Checkout-и репозиторію завантажують вбудований раннер напряму; окремий крок встановлення 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 не надає спільних прапорців джерела облікових даних, оскільки цей канал локально створює тимчасових користувачів. + - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований лог stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA-гілку Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Запускає Telegram live QA-канал проти реальної приватної групи, використовуючи токени driver і SUT-бота з env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути оренду зі спільного пулу. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має надавати ім’я користувача Telegram. - - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані спільні облікові дані. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає помилки. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому SUT-бот має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver-бот може спостерігати трафік ботів у групі. + - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. -Live-транспортні гілки мають єдиний стандартний контракт, щоб нові транспорти не відхилялися: +Live-канали транспорту мають один спільний стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live-транспортів. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live-транспортів. -| Гілка | 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 | -### Спільні облікові дані Telegram через Convex (v1) +### Спільні Telegram-облікові дані через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat для цієї оренди під час роботи гілки та звільняє оренду під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, підтримує Heartbeat цієї оренди, поки канал працює, і звільняє оренду під час завершення роботи. -Еталонний каркас проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` @@ -112,7 +114,7 @@ Live-транспортні гілки мають єдиний стандарт - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `maintainer`) + - Типове значення з env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) Необов’язкові змінні середовища: @@ -121,15 +123,14 @@ Live-транспортні гілки мають єдиний стандарт - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий ідентифікатор трасування) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback-URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-и Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністраторські команди підтримувача (додавання/видалення/список пулу) вимагають саме -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди maintainer-а (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні CLI-команди для підтримувачів: +CLI-хелпери для maintainer-ів: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -137,7 +138,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. +Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -151,18 +152,18 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет підтримувача) +- `POST /admin/add` (лише секрет maintainer-а) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет підтримувача) +- `POST /admin/remove` (лише секрет maintainer-а) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише секрет підтримувача) +- `POST /admin/list` (лише секрет maintainer-а) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма payload для виду Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` має бути рядком із числовим ідентифікатором чату Telegram. @@ -170,54 +171,54 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання каналу до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Щоб додати канал до markdown-системи QA, потрібні рівно дві речі: -1. Транспортного адаптера для каналу. -2. Пакета сценаріїв, який перевіряє контракт каналу. +1. Транспортний адаптер для каналу. +2. Пакет сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може керувати цим процесом. +Не додавайте новий кореневий QA-командний namespace верхнього рівня, якщо спільний хост `qa-lab` може керувати цим потоком. `qa-lab` володіє спільною механікою хоста: - кореневою командою `openclaw qa` - запуском і завершенням набору -- конкурентністю воркерів +- паралелізмом воркерів - записом артефактів - генерацією звітів - виконанням сценаріїв -- alias сумісності для старіших сценаріїв `qa-channel` +- aliases сумісності для старіших сценаріїв `qa-channel` -Plugin ранери володіють транспортним контрактом: +Runner plugins володіють транспортним контрактом: -- як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway конфігурується для цього транспорту +- як `openclaw qa ` монтується під спільний корінь `qa` +- як gateway налаштовується для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти й нормалізований стан транспорту -- як виконуються дії на основі транспорту +- як надаються транскрипти та нормалізований стан транспорту +- як виконуються дії, пов’язані з транспортом - як обробляється специфічне для транспорту скидання або очищення -Мінімальний поріг впровадження для нового каналу: +Мінімальна планка для впровадження нового каналу: -1. Зберігайте `qa-lab` як власника спільного кореня `qa`. -2. Реалізуйте транспортний раннер на спільному шві хоста `qa-lab`. -3. Зберігайте транспортно-специфічну механіку всередині Plugin раннера або harness каналу. -4. Монтуйте раннер як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Plugin ранери мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і раннера має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні допоміжні функції сценаріїв для нових сценаріїв. -7. Зберігайте наявні alias сумісності працездатними, якщо в репозиторії не виконується навмисна міграція. +1. Залишити `qa-lab` власником спільного кореня `qa`. +2. Реалізувати transport runner на спільному host seam `qa-lab`. +3. Залишити транспортно-специфічну механіку всередині runner plugin або channel harness. +4. Монтувати раннер як `openclaw qa `, а не реєструвати конкуруючий кореневий командний namespace. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Тримайте `runtime-api.ts` легким; ліниве виконання CLI й раннера має залишатися за окремими entrypoint-ами. +5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовувати загальні scenario helpers для нових сценаріїв. +7. Зберігати працездатність наявних aliases сумісності, якщо в репозиторії не виконується навмисна міграція. Правило прийняття рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного канального транспорту, зберігайте її в цьому Plugin раннера або harness Plugin. -- Якщо сценарію потрібна нова можливість, яку можуть використовувати більш ніж один канал, додавайте загальний helper замість канально-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, зберігайте сценарій транспортно-специфічним і явно вказуйте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного транспортного каналу, залишайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальний helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію. -Бажані загальні назви helper для нових сценаріїв: +Бажані назви загальних helper-ів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -232,7 +233,7 @@ Plugin ранери володіють транспортним контракт - `formatTransportTranscript` - `resetTransport` -Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: +Aliases сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -240,245 +241,245 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота з каналами має використовувати загальні назви helper. -Alias сумісності існують, щоб уникнути міграції «у визначений день», а не як модель для +Нова робота над каналами має використовувати загальні назви helper-ів. +Aliases сумісності існують, щоб уникнути міграції «в один день», а не як модель для створення нових сценаріїв. -## Тестові набори (що де запускається) +## Набори тестів (що де запускається) Сприймайте набори як такі, що мають «зростаючий реалізм» (і зростаючу нестабільність/вартість): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфіг: десять послідовних запусків шардованих конфігурацій (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest -- Файли: core/unit-інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, охоплені `vitest.unit.config.ts` +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest +- Файли: core/unit-інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Інтеграційні тести в межах процесу (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка щодо проєктів: - - `pnpm test` без явного націлювання тепер запускає одинадцять менших шардованих конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` як і раніше використовує граф проєктів native root `vitest.config.ts`, тому що цикл watch із багатьма шардами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped-гілки, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-гілки, коли diff торкається лише routable source/test-файлів; редагування config/setup, як і раніше, повертаються до широкого повторного запуску root-project. - - Легкі unit-тести з agents, commands, plugins, helper auto-reply, `plugin-sdk` та подібних суто утилітарних ділянок маршрутизуються через гілку `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних гілках. - - Вибрані helper-вихідники `plugin-sdk` і `commands` також прив’язують запуски в режимі changed до явних sibling-тестів у цих легких гілках, щоб редагування helper не змушували повторно запускати весь важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі кошики: top-level core helper, top-level інтеграційні тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. -- Примітка щодо embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, +- Примітка про проєкти: + - Нетаргетований `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension заважати іншим наборам. + - `pnpm test --watch` і далі використовує граф native root `vitest.config.ts`, оскільки багатошардовий цикл watch непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через scoped-канали, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-канали, коли diff зачіпає лише маршрутизовані source/test-файли; зміни config/setup, як і раніше, повертаються до широкого повторного запуску root-project. + - Import-light unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через канал `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних каналах. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких каналах, тож зміни helper-ів не змушують повторно запускати повний важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі кошики: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. +- Примітка про embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime Compaction, зберігайте обидва рівні покриття. - - Додавайте цілеспрямовані helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте в належному стані інтеграційні набори embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. + - Також підтримуйте в хорошому стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction, як і раніше, проходять - через реальні шляхи `run.ts` / `compact.ts`; одних лише helper-тестів недостатньо - як заміни цим інтеграційним шляхам. -- Примітка щодо pool: - - Базовий конфіг Vitest тепер типово використовує `threads`. - - Спільний конфіг Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live-конфігах. - - Root-гілка 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. -- Примітка щодо швидкої локальної ітерації: - - `pnpm test:changed` маршрутизує через scoped-гілки, коли змінені шляхи однозначно відповідають меншому набору. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею воркерів. - - Автомасштабування локальних воркерів тепер навмисно більш консервативне і також відступає, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базовий конфіг Vitest позначає проєкти/конфіг-файли як `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` із native root-project шляхом для цього закоміченого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфіг Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main thread для startup і transform overhead у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для unit-набору з вимкненим файловим паралелізмом. + - Ці набори перевіряють, що scoped ids і поведінка Compaction як і раніше проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих integration-шляхів. +- Примітка про pool: + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live-конфігураціях. + - Кореневий канал 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. +- Примітка про швидку локальну ітерацію: + - `pnpm test:changed` маршрутизує через scoped-канали, коли змінені шляхи добре зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості воркерів. + - Локальне автомасштабування воркерів тепер навмисно консервативне й також зменшується, коли середнє навантаження хоста вже високе, тож кілька паралельних запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні changed-mode запуски залишалися коректними, коли змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете мати одну явну локацію кешу для прямого профілювання. +- Примітка про налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід розбивки імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими від `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього закоміченого diff і виводить wall time плюс macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner-а для unit-набору з вимкненим файловим паралелізмом. -### E2E (Gateway smoke) +### E2E (smoke Gateway) - Команда: `pnpm test:e2e` -- Конфіг: `vitest.e2e.config.ts` +- Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. +- Типові налаштування runtime: + - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на консольний I/O. + - Типово запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний консольний вивід. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Поведінка end-to-end Gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, сполучення Node і складніша мережева взаємодія + - End-to-end поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, парування Node і важчий мережевий стек - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke для backend OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell Gateway на хості через Docker + - Запускає ізольований OpenShell gateway на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє канонічну поведінку віддаленої файлової системи через fs bridge sandbox + - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Підтверджує поведінку файлової системи remote-canonical через sandbox fs bridge - Очікування: - - Лише за запитом; не входить до типового запуску `pnpm test:e2e` + - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - Потребує локального CLI `openshell` і працездатного демона Docker - - Використовує ізольовані `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-скрипт + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфіг: `vitest.live.config.ts` +- Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- Типово: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`) +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки обмежень швидкості + - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / витрачає rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски підхоплюють `~/.profile`, щоб отримати відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації в тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Задавайте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує журнали bootstrap Gateway/шум Bonjour. Задайте `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. -- Ротація API-ключів (специфічна для провайдера): задавайте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи перевизначення на рівні live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Live-запуски використовують `~/.profile`, щоб підхоплювати відсутні API-ключі. +- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і глушить логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежить від провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення на рівні live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні навіть тоді, коли перехоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/Gateway транслюються негайно під час live-запусків. - - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер надсилають рядки прогресу в stderr, тож довгі виклики провайдера видно як активні, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway негайно транслювалися під час live-запусків. + - Налаштовуйте Heartbeat прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо зміни великі) -- Торкаєтесь мережевої взаємодії Gateway / протоколу WS / сполучення: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зачіпаєте мережеву взаємодію gateway / протокол WS / парування: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, що наразі рекламується** підключеним Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android Node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не сполучає застосунок). - - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. -- Необхідне попереднє налаштування: - - Android-застосунок уже підключений і сполучений із Gateway. + - Передумови/ручне налаштування (набір не встановлює, не запускає й не парує застосунок). + - Перевірка `node.invoke` gateway команда за командою для вибраного Android Node. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключений і спарений із gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте як успішні. + - Надано дозволи/підтвердження захоплення для можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) +- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke для моделей (ключі профілів) +## Live: smoke моделі (ключі профілю) -Live-тести поділено на два шари, щоб ми могли ізолювати збої: +Live-тести розділені на два рівні, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, що провайдер/модель взагалі може відповісти з наданим ключем. +- «Gateway smoke» показує, що повний конвеєр gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Шар 1: пряме завершення моделі (без Gateway) +### Рівень 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де це потрібно) + - Перерахувати виявлені моделі + - Використовувати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) -- Задайте `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб фактично запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на smoke Gateway + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на smoke Gateway - Як вибирати моделі: - - `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=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Розгортки modern/all типово обмежуються curated high-signal cap; задайте `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-розгортки або додатне число для меншого ліміту. + - Перегляди modern/all типово мають curated high-signal обмеження; установіть `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 fallback-и + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр Gateway agent зламаний» - - Містить невеликі, ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить малі, ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: smoke Gateway + dev agent (що насправді робить "@openclaw") +### Рівень 2: smoke Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Запустити in-process Gateway - - Створити/змінити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по моделях-із-ключами та перевіряти: + - Підняти in-process gateway + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітерувати моделі-з-ключами й перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (перевірка read) + - що реальний виклик інструмента працює (перевірка read) - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) залишаються працездатними -- Деталі перевірок (щоб ви могли швидко пояснювати збої): - - Перевірка `read`: тест записує nonce-файл у workspace і просить agent виконати `read` цього файлу та повернути nonce. - - Перевірка `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - Перевірка зображення: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють +- Деталі probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - image probe: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist - - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Розгортки modern/all для Gateway типово обмежуються curated high-signal cap; задайте `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-розгортки або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникнути «усе в OpenRouter»): + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Перегляди modern/all для gateway типово мають curated high-signal обмеження; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-перегляду або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникайте «OpenRouter для всього»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки інструментів і зображень у цьому live-тесті завжди ввімкнені: - - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) - - перевірка зображення запускається, коли модель заявляє підтримку вхідних зображень +- Tool + image probe у цьому live-тесті завжди ввімкнені: + - `read` probe + `exec+read` probe (stress для інструментів) + - image probe запускається, коли модель заявляє підтримку введення зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки дозволені) + - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent передає multimodal повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI-backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI-backend, не торкаючись вашої типової конфігурації. -- Типові smoke-параметри, специфічні для backend, знаходяться у визначенні `cli-backend.ts` відповідного Plugin. +- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не зачіпаючи вашу типову конфігурацію. +- Типові значення smoke, специфічні для backend, розміщено у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типові провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image походить із метаданих Plugin відповідного CLI-backend. + - Типовий provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image походить із metadata 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`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності однієї сесії Claude Sonnet -> Opus (задайте `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як CLI-аргументи замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий turn і перевірити потік відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типовий probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -494,7 +495,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -505,29 +506,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані CLI smoke з відповідного Plugin, а потім встановлює відповідний 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` потребує portable OAuth передплати Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Ця гілка передплати типово вимикає перевірки Claude MCP/tool і image, тому що Claude зараз маршрутизує використання сторонніх застосунків через billing додаткового використання, а не через звичайні ліміти тарифного плану передплати. -- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-раннер розташовано в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає metadata CLI smoke від extension-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносного OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два Gateway CLI-backend turns без збереження env-змінних ключа Anthropic API. Цей канал підписки типово вимикає Claude MCP/tool і image probe, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra-usage, а не через звичайні ліміти тарифного плану підписки. +- Smoke live CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий turn, turn класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke Claude також оновлює сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP agent: +- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці + - прив’язати synthetic розмову каналу повідомлень на місці - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє в transcript прив’язаної сесії ACP + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agent у 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` + - Synthetic канал: контекст розмови у стилі Slack DM + - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -535,8 +536,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця гілка використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр agent Plugin `acpx` для вибраного ACP harness agent. + - Цей канал використовує поверхню gateway `chat.send` з admin-only synthetic originating-route полями, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -552,7 +553,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent: +Docker-рецепти для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -562,31 +563,31 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. +- 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 в контейнері, встановлює `acpx` у npm-префікс із можливістю запису, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. -- Усередині Docker ранер задає `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підхопленого профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у записуваний npm-prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підключеного profile доступними для дочірнього harness CLI. ## Live: smoke harness app-server Codex -- Мета: перевірити Plugin-власний harness Codex через звичайний метод - `agent` у Gateway: - - завантажити вбудований Plugin `codex` +- Мета: перевірити plugin-власний harness Codex через звичайний метод gateway + `agent`: + - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread - app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий шлях - команди Gateway + - надіслати перший gateway agent turn до `codex/gpt-5.4` + - надіслати другий turn до тієї самої сесії OpenClaw і перевірити, що thread app-server + можна відновити + - виконати `/codex status` і `/codex models` через той самий командний шлях + gateway - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язкова перевірка зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова перевірка MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Цей smoke задає `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти перевірку через тихий fallback до PI. -- Автентифікація: `OPENAI_API_KEY` з shell/profile, плюс необов’язково скопійовані +- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти, тихо переключившись назад на PI. +- Auth: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -609,28 +610,28 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він підхоплює змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони присутні, встановлює `@openai/codex` у змонтований npm-префікс - із можливістю запису, розміщує вихідне дерево, а потім запускає лише live-тест Codex-harness. -- У Docker перевірки image і MCP/tool увімкнені типово. Задайте +- Docker-раннер розташовано в `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm + prefix, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає image- і MCP/tool-probe. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, узгоджено з live- - конфігом тесту, щоб fallback до `openai-codex/*` або PI не міг приховати регресію - harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли вам потрібен вужчий налагоджувальний запуск. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до live + конфігурації тесту, щоб fallback на `openai-codex/*` або PI не міг приховати регресію + Codex harness. ### Рекомендовані live-рецепти -Вузькі, явні allowlist — найшвидші та найменш нестабільні: +Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: -- Одна модель, direct (без Gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, smoke Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів для кількох провайдерів: +- Виклик інструментів у кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -640,17 +641,17 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує API Gemini (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості tooling). - API Gemini проти CLI Gemini: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (автентифікація через API-ключ / профіль); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарник `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розсинхронізація версій). + - API: OpenClaw викликає хостований Google API Gemini через HTTP (API-ключ / автентифікація профілю); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). ## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (live вмикається за запитом), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Немає фіксованого «списку моделей CI» (live запускається лише за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний набір smoke (виклик інструментів + image) +### Сучасний smoke-набір (виклик інструментів + зображення) Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: @@ -662,10 +663,10 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск smoke Gateway з інструментами + image: +Запустіть smoke Gateway з інструментами + зображенням: `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) +### Базовий набір: виклик інструментів (Read + необов’язковий Exec) Виберіть щонайменше одну модель для кожного сімейства провайдерів: @@ -675,30 +676,30 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель з підтримкою `tools`, яку ви ввімкнули) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою «tools», яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → multimodal-повідомлення) -Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI із підтримкою vision тощо), щоб перевірити image probe. +Включіть щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні Gateway +### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (кастомні endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), плюс будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зашити в документацію «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + які ключі доступні. +Порада: не намагайтеся жорстко прописати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) @@ -707,49 +708,49 @@ Live-тести виявляють облікові дані так само, я - Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілів») -- Конфіг: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог зі старим станом: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але не є основним сховищем ключів профілів) -- Локальні live-запуски типово копіюють активний конфіг, файли `auth-profiles.json` для кожного agent, старий каталог `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального workspace хоста. +- Профілі автентифікації на рівні агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home, якщо присутній, але це не основне сховище ключів профілю) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий тестовий home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe-и не зачіпали ваш реальний workspace хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть змонтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live: Deepgram (транскрибування аудіо) +## Deepgram live (транскрипція аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live: план кодування BytePlus +## BytePlus coding plan live - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа робочого процесу ComfyUI +## ComfyUI workflow media live - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи image, video і `music_generate` у comfy - - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у відправленні робочих процесів comfy, polling, завантаженнях або реєстрації Plugin + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` + - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано + - Корисно після змін у відправленні workflow comfy, polling, завантаженнях або реєстрації plugin -## Live: генерація image +## Live генерації зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований Plugin провайдера генерації image - - Завантажує відсутні env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Перераховує кожен зареєстрований provider plugin генерації зображень + - Завантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Проганяє стандартні варіанти генерації image через спільну runtime-можливість: + - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери в покритті: +- Поточні вбудовані провайдери, які покриваються: - `openai` - `google` - Необов’язкове звуження: @@ -757,97 +758,97 @@ Live-тести виявляють облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env -## Live: генерація музики +## Live генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації музики + - Перевіряє спільний вбудований шлях provider-а генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені режими runtime, коли вони доступні: - - `generate` з введенням лише prompt + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` із введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної гілки: + - Поточне покриття спільного каналу: - `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+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env -## Live: генерація відео +## Live генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації відео - - Типово використовує release-safe шлях smoke: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt із lobster і обмеження часу операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` типово) - - Типово пропускає FAL, тому що затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити - - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Перевіряє спільний вбудований шлях provider-а генерації відео + - Типово використовує release-safe smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster prompt і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - Типово пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити + - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Типово запускає лише `generate` - - Задайте `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення image на основі buffer у спільній розгортці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення video на основі buffer у спільній розгортці - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільній розгортці: - - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL image - - Покриття Vydra, специфічне для провайдера: + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає локальне введення зображення через buffer-backed у спільному перегляді + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає локальне введення відео через buffer-backed у спільному перегляді + - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільному перегляді: + - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддалений URL зображення + - Специфічне для провайдера покриття Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс гілку `kling`, яка типово використовує фікстуру з віддаленим URL image + - цей файл запускає `veo3` text-to-video плюс канал `kling`, який типово використовує фікстуру віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільній розгортці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 - - `google`, тому що поточна спільна гілка Gemini/Veo використовує локальне введення на основі buffer, і цей шлях не приймається у спільній розгортці - - `openai`, тому що поточна спільна гілка не гарантує доступ до org-специфічних можливостей video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільному перегляді: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз потребують віддалені референсні URL `http(s)` / MP4 + - `google`, оскільки поточний спільний канал Gemini/Veo використовує локальне buffer-backed введення, і цей шлях не приймається в спільному перегляді + - `openai`, оскільки поточний спільний канал не гарантує доступ до video inpaint/remix, специфічний для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової розгортки, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт часу операції для кожного провайдера під час агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового перегляду, зокрема FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт часу операції для кожного провайдера для агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один repo-native entrypoint + - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` + - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `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-ранери (необов’язкові перевірки «працює в Linux») +## Docker-раннери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці Docker-раннери поділяються на дві групи: -- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл профільних ключів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог конфігурації та workspace (і підхоплюючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери типово використовують менший smoke-ліміт, щоб повна Docker-розгортка залишалася практичною: +- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл з ключами профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker-раннери live типово мають менше обмеження smoke, щоб повний Docker-перегляд залишався практичним: `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібне ширше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-гілок live. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібен більший вичерпний перегляд. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-каналів live. +- Раннери smoke контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Live-model Docker-ранери також bind-mount лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без змінення сховища автентифікації хоста: +Docker-раннери live-моделей також bind-mount-ять лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи сховище автентифікації хоста: - Прямі моделі: `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`) @@ -855,104 +856,106 @@ Live-model Docker-ранери також bind-mount лише потрібні h - Smoke harness app-server Codex: `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, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Майстер onboarding (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) - Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Live-model Docker-ранери також bind-mount поточну копію checkout у режимі лише для читання і -розміщують її в тимчасовому workdir усередині контейнера. Це зберігає runtime- -образ компактним, але водночас дозволяє запускати Vitest точно на вашому локальному вихідному коді/конфігурації. -Крок staging пропускає великі локальні кеші та результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -реальні канальні воркери Telegram/Discord тощо всередині контейнера. +Docker-раннери live-моделей також bind-mount-ять поточний checkout лише для читання і +підготовлюють його у тимчасовий workdir усередині контейнера. Це робить runtime-образ +компактним, але все одно дає змогу запускати Vitest проти точно вашої локальної source/config. +Крок підготовки пропускає великі локальні кеші та артефакти збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або +виводу Gradle, тож Docker live-запуски не витрачають хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe-и gateway не запускали +реальні воркери каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити live-покриття Gateway з цієї Docker-гілки. -`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP-endpoint, -запускає прив’язаний контейнер Open WebUI проти цього Gateway, виконує вхід через +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway +live-покриття з цього Docker-каналу. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP-endpoint-ами, +запускає закріплений контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` в Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -образу Open WebUI, а Open WebUI — завершення власного cold-start налаштування. -Ця гілка потребує придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Docker-запусках. -Успішні запуски друкують невеликий JSON-payload на кшталт `{ "ok": true, "model": +реальний chat-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження +образу Open WebUI, а сам Open WebUI може завершувати власний cold-start setup. +Цей канал очікує наявність придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway- -контейнер, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і канальні сповіщення -у стилі Claude + сповіщення про дозволи через реальний stdio MCP bridge. Перевірка notification -безпосередньо інспектує raw stdio MCP frame, тож smoke перевіряє те, що міст -справді надсилає, а не лише те, що певний SDK клієнта випадково відображає. +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway +контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення каналів + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP-фрейми, тож smoke перевіряє те, що bridge +справді випромінює, а не лише те, що випадково показує конкретний client SDK. -Ручний smoke plain-language thread ACP (не для CI): +Ручний smoke звичайною мовою для ACP thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації thread ACP, тож не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підхоплюється перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підхоплені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI-автентифікації -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються в режимі лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підключені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх mount-ів автентифікації CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI у Docker +- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується у smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег образу Open WebUI + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначення вручну: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків без перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять із profile store (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки документації після редагування документів: `pnpm check:docs`. -Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування docs: `pnpm check:docs`. +Запускайте повну перевірку anchor-ів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайнова регресія (безпечна для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: - Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує конфігурацію + примусову автентифікацію): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис конфігурації + примусова автентифікація): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Оцінювання надійності агента (Skills) -У нас уже є кілька тестів, безпечних для CI, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: - Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють обв’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає agent правильний Skill (або уникає нерелевантних)? -- **Відповідність:** чи читає agent `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок виклику інструментів, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли в prompt перелічено Skills, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. -Майбутні eval спочатку мають залишатися детермінованими: +Майбутні eval-и мають насамперед залишатися детермінованими: -- Ранер сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання файлів Skill і обв’язки сесії. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gate, prompt injection). -- Необов’язкові live-eval (за запитом, із gate через env) лише після того, як буде готовий набір, безпечний для CI. +- Scenario runner із mock-провайдерами для перевірки викликів tool + порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на skill-ах (використати чи уникнути, gating, prompt injection). +- Необов’язкові live eval-и (за явним увімкненням, із gating через env) — лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма Plugin і channel) +## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір перевірок форми та поведінки. Типова unit-гілка `pnpm test` навмисно +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +контракту інтерфейсу. Вони проходять по всіх виявлених plugin-ах і запускають набір +перевірок форми та поведінки. Типовий unit-канал `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +коли зачіпаєте спільні поверхні channel або provider. ### Команди @@ -964,14 +967,14 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) +- **plugin** - Базова форма plugin (`id`, `name`, `capabilities`) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка ID тредів -- **directory** - API каталогу/реєстру +- **threading** - Обробка ідентифікаторів тредів +- **directory** - API каталогу/списку учасників - **group-policy** - Застосування групової політики ### Контракти статусу provider @@ -979,7 +982,7 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/plugins/contracts/*.contract.test.ts`. - **status** - Перевірки статусу channel -- **registry** - Форма реєстру Plugin +- **registry** - Форма реєстру plugin ### Контракти provider @@ -988,29 +991,29 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa - **auth** - Контракт потоку автентифікації - **auth-choice** - Вибір/добір автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin - **runtime** - Runtime provider -- **shape** - Форма/інтерфейс Plugin +- **shape** - Форма/інтерфейс plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після змін експортів або subpath у plugin-sdk -- Після додавання або зміни channel чи provider Plugin -- Після рефакторингу реєстрації або виявлення Plugin +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin +- Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI й не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Додайте регресію, безпечну для CI, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою існує лише в live (rate limits, політики автентифікації), залишайте live-тест вузьким і таким, що вмикається через env-змінні -- Намагайтеся націлюватися на найменший шар, який ловить помилку: - - помилка конвертації/повторного програвання запиту provider → тест direct models - - помилка конвеєра Gateway session/history/tool → live smoke Gateway або безпечний для CI mock-тест Gateway +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точну трансформацію форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), залишайте live-тест вузьким і з явним увімкненням через env-змінні +- Віддавайте перевагу найменшому рівню, який виявляє помилку: + - помилка перетворення/повторення запиту provider → direct models test + - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway - Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих id цілей, щоб нові класи не можна було тихо пропустити. + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити.