From 19b599bba855f93b9e48b4563012eb8b7a63397c Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 23:39:42 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/qa-e2e-automation.md | 169 +++--- docs/uk/help/testing.md | 738 +++++++++++++------------- 2 files changed, 482 insertions(+), 425 deletions(-) diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index f8f3817f6..cf74f37bf 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,36 +1,37 @@ --- read_when: - Розширення qa-lab або qa-channel - - Додавання сценаріїв QA, що підтримуються репозиторієм - - Побудова більш реалістичної автоматизації QA навколо панелі керування Gateway -summary: Приватна структура автоматизації QA для qa-lab, qa-channel, підготовлених сценаріїв і звітів протоколу + - Додавання сценаріїв QA з підтримкою репозиторію + - Створення більш реалістичної автоматизації QA навколо панелі керування Gateway +summary: Приватна структура автоматизації QA для qa-lab, qa-channel, початково заповнених сценаріїв і звітів протоколу title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-10T12:52:46Z" + generated_at: "2026-04-10T23:36:40Z" model: gpt-5.4 provider: openai - source_hash: e416ffd285a05339a88eb749e37c4ed9448f232ca67dc0c85eba772029b5b306 + source_hash: 5427b505e26bfd542e984e3920c3f7cb825473959195ba9737eff5da944c60d0 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Автоматизація QA E2E -Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, +Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний, орієнтований на канали спосіб, ніж це може зробити один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, - реакцій, редагування та видалення. +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, гілки, + реакції, редагування та видалення. - `extensions/qa-lab`: UI налагодження та шина QA для спостереження за транскриптом, - інʼєкції вхідних повідомлень і експорту звіту у форматі Markdown. -- `qa/`: ресурси початкових даних, що підтримуються репозиторієм, для стартового завдання та базових сценаріїв QA. + інʼєкції вхідних повідомлень і експорту Markdown-звіту. +- `qa/`: ресурси початкового заповнення з підтримкою репозиторію для стартового завдання та базових QA + сценаріїв. -Поточний потік роботи оператора QA — це сайт QA із двома панелями: +Поточний робочий процес оператора QA — це сайт QA з двома панелями: - Ліворуч: панель керування Gateway (Control UI) з агентом. -- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. +- Праворуч: QA Lab, де показано транскрипт у стилі Slack і план сценарію. Запустіть його так: @@ -38,12 +39,11 @@ x-i18n: 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,60 +53,100 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` утримує сервіси Docker на попередньо зібраному образі та bind-mount +`qa:lab:up:fast` зберігає сервіси Docker на попередньо зібраному образі та bind-mount-ить `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перезбирає цей пакет при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. +перезбирає цей bundle під час змін, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. -Для тимчасового lane на Linux VM без залучення Docker до шляху QA виконайте: +Для лінії smoke-тестування Matrix із реальним транспортом запустіть: + +```bash +pnpm openclaw qa matrix +``` + +Ця лінія розгортає одноразовий homeserver Tuwunel у Docker, реєструє +тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, а потім запускає +реальний плагін Matrix усередині дочірнього процесу QA gateway. Лінія з живим транспортом зберігає конфігурацію дочірнього процесу в межах транспорту, що тестується, тому Matrix працює без +`qa-channel` у конфігурації дочірнього процесу. + +Для лінії smoke-тестування Telegram із реальним транспортом запустіть: + +```bash +pnpm openclaw qa telegram +``` + +Ця лінія використовує одну реальну приватну групу 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`. + +Лінії з живим транспортом тепер використовують один менший спільний контракт замість того, щоб кожна вигадувала +власну форму списку сценаріїв: + +`qa-channel` залишається широким набором синтетичних тестів поведінки продукту і не входить +до матриці покриття живого транспорту. + +| Лінія | Канарка | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у гілці | Ізоляція гілки | Спостереження за реакціями | Команда help | +| -------- | ------- | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | -------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +Це зберігає `qa-channel` як широкий набір тестів поведінки продукту, тоді як Matrix, +Telegram і майбутні живі транспорти використовують один явний контрольний список транспортного контракту. + +Для одноразової лінії Linux VM без включення Docker у шлях QA запустіть: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує свіжий гість Multipass, встановлює залежності, збирає OpenClaw -усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт QA і +Це завантажує свіжу гостьову машину Multipass, встановлює залежності, збирає OpenClaw +усередині гостьової машини, запускає `qa suite`, а потім копіює звичайний звіт QA та підсумок назад у `.artifacts/qa-e2e/...` на хості. -Використовується та сама поведінка вибору сценаріїв, що й у `qa suite` на хості. +Воно повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими працівниками gateway, до 64 працівників або до кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість працівників, або +з ізольованими воркерами gateway, до 64 воркерів або до кількості вибраних +сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для послідовного виконання. -Live-запуски пересилають підтримувані вхідні дані автентифікації QA, які практичні для -гостя: ключі провайдера на основі env, шлях до конфігурації live-провайдера QA і -`CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість -міг записувати результати назад через змонтований робочий простір. +Живі запуски передають підтримувані вхідні дані автентифікації QA, які практично використовувати для +гостьової машини: ключі провайдера на основі env, шлях до конфігурації live-провайдера QA та +`CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гостьова машина +могла записувати назад через змонтований workspace. -## Початкові дані, що підтримуються репозиторієм +## Початкові дані з підтримкою репозиторію -Ресурси початкових даних розташовані в `qa/`: +Ресурси початкового заповнення знаходяться в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і -агенту. Базовий список має залишатися достатньо широким, щоб охоплювати: +Вони навмисно зберігаються в git, щоб план QA був видимим як для людей, так і для +агента. Базовий список має залишатися достатньо широким, щоб охоплювати: -- DM і чат у каналі -- поведінку тредів +- чат у DM і каналі +- поведінку гілок - життєвий цикл дій із повідомленнями -- cron-зворотні виклики -- відтворення памʼяті +- cron callbacks +- відновлення памʼяті - перемикання моделей -- передачу субагенту +- передачу підагенту - читання репозиторію та документації - одне невелике завдання зі збирання, наприклад Lobster Invaders ## Звітність -`qa-lab` експортує звіт протоколу у форматі Markdown зі спостережуваної часової шкали шини. -Звіт має відповідати на запитання: +`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. +Звіт має відповідати на такі питання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим -- Які сценарії продовження варто додати +- Які подальші сценарії варто додати -Для перевірок характеру та стилю запустіть той самий сценарій для кількох live-моделей -і запишіть оцінений звіт у форматі Markdown: +Для перевірки характеру та стилю запустіть той самий сценарій для кількох live-моделей +і створіть оцінений Markdown-звіт: ```bash pnpm openclaw qa character-eval \ @@ -125,39 +165,38 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Ця команда запускає локальні дочірні процеси gateway QA, а не Docker. Сценарії оцінювання характеру -мають задавати персону через `SOUL.md`, а потім виконувати звичайні ходи користувача, -такі як чат, допомога з робочим простором і невеликі файлові завдання. Моделі-кандидату -не слід повідомляти, що її оцінюють. Команда зберігає кожен повний транскрипт, -записує базову статистику запуску, а потім просить моделі-судді у fast mode з -міркуванням `xhigh` ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` при порівнянні провайдерів: підказка для судді все одно отримує -кожен транскрипт і статус запуску, але посилання кандидатів замінюються на нейтральні -мітки, такі як `candidate-01`; після розбору звіт зіставляє ранжування з реальними посиланнями. -Запуски кандидатів за замовчуванням використовують `high` thinking, а для моделей OpenAI — `xhigh`, -якщо вони це підтримують. Перевизначте конкретного кандидата inline через -`--model provider/model,thinking=`. `--thinking ` усе ще задає +Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії оцінювання характеру +мають задавати persona через `SOUL.md`, а потім запускати звичайні користувацькі ходи, +такі як чат, допомога з workspace і невеликі файлові завдання. Моделі-кандидату +не слід повідомляти, що її оцінюють. Команда зберігає кожен повний +транскрипт, записує базову статистику запуску, а потім просить моделі-судді в режимі fast з +міркуванням `xhigh` ранжувати запуски за природністю, атмосферою та гумором. +Використовуйте `--blind-judge-models` під час порівняння провайдерів: підказка для судді все одно отримує +кожен транскрипт і статус запуску, але посилання кандидатів замінюються нейтральними +мітками, такими як `candidate-01`; після розбору звіту ранжування зіставляється назад із реальними посиланнями. +Для запусків кандидатів за замовчуванням використовується рівень thinking `high`, а для моделей OpenAI, що це підтримують, — `xhigh`. Перевизначте конкретного кандидата вбудовано через +`--model provider/model,thinking=`. `--thinking ` як і раніше задає глобальний резервний варіант, а старіша форма `--model-thinking ` зберігається для сумісності. -Посилання кандидатів OpenAI за замовчуванням використовують fast mode, щоб за можливості провайдера -застосовувалася обробка з пріоритетом. Додайте inline `,fast`, `,no-fast` або `,fast=false`, якщо -окремому кандидату чи судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів -записується у звіті для аналізу бенчмарків, але підказки для суддів явно вказують +Посилання кандидатів OpenAI за замовчуванням використовують режим fast, щоб застосовувалася пріоритетна обробка там, +де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` вбудовано, коли для +окремого кандидата чи судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете +примусово ввімкнути режим fast для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +записується у звіт для аналізу бенчмарків, але в підказках для суддів явно сказано не ранжувати за швидкістю. -І запуски моделей-кандидатів, і запуски моделей-суддів за замовчуванням мають concurrency 16. Зменшуйте -`--concurrency` або `--judge-concurrency`, якщо обмеження провайдера або навантаження на локальний gateway +І для запусків моделей-кандидатів, і для моделей-суддів за замовчуванням використовується concurrency 16. Зменшіть +`--concurrency` або `--judge-concurrency`, коли обмеження провайдера або навантаження на локальний gateway роблять запуск надто шумним. -Якщо не передано жодного кандидатського `--model`, оцінювання характеру за замовчуванням використовує +Якщо не передано жодного candidate `--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`, суддями за замовчуванням є +Якщо не передано `--judge-model`, за замовчуванням як судді використовуються `openai/gpt-5.4,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. ## Повʼязана документація -- [Тестування](/uk/help/testing) +- [Testing](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) -- [Панель керування](/web/dashboard) +- [Dashboard](/web/dashboard) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 2c1bd5dc8..0cb260136 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,308 +1,327 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделі/провайдера - - Налагодження поведінки gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та те, що охоплює кожен тест' + - Додавання регресій для помилок моделей/провайдерів + - Налагодження поведінки шлюзу й агента +summary: 'Набір для тестування: модульні/e2e/live набори, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-10T23:15:01Z" + generated_at: "2026-04-10T23:36:40Z" model: gpt-5.4 provider: openai - source_hash: 1ef760f5cc65d0c0eaf0113350a870ba76e1b40b6754f949b53ed62e7e1e92bd + source_hash: 55e75d056306a77b0d112a3902c08c7771f53533250847fc3d785b1df3e0e9e7 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір раннерів Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) -- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем із моделями/провайдерами +- Які команди запускати для типових робочих сценаріїв (локально, перед 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-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Якщо ви ітеруєтеся над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на основі Docker: `pnpm qa:lab:up` +- QA-смуга на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете більшої впевненості: -- Gate покриття: `pnpm test:coverage` +- Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, краще звужуйте live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## Спеціальні QA-раннери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або до кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішого послідовного lane. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або кількості вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування кількості workers або `--concurrency 1` для старішої послідовної смуги. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у тимчасовій Multipass Linux VM. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Під час live-запусків пересилає підтримувані QA auth inputs, які практично використовувати в guest: - env-based provider keys, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт і summary, а також Multipass-логи до + - Live-запуски пересилають підтримувані QA-входи автентифікації, які практичні для гостьової системи: + ключі провайдерів на основі env, шлях конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. + - Записує звичайний QA-звіт + підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в стилі оператора. + - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. +- `pnpm openclaw qa matrix` + - Запускає live QA-смугу Matrix проти одноразового Docker-backed homeserver Tuwunel. + - Піднімає трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним плагіном Matrix як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Записує Matrix QA-звіт, підсумок і артефакт observed-events у `.artifacts/qa-e2e/...`. +- `pnpm openclaw qa telegram` + - Запускає live QA-смугу Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим Telegram chat id. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати ім’я користувача Telegram. + - Для стабільного спостереження між ботами увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати за трафіком ботів у групі. + - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. -## Набори тестів (що де запускається) +Live transport lanes мають спільний стандартний контракт, щоб нові транспорти не розходилися: + +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. + +| Смуга | Canary | Mention gating | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в потоці | Ізоляція потоку | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | --------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +## Тестові набори (що де запускається) Сприймайте набори як «зростаючий реалізм» (і зростаючу нестабільність/вартість): -### Unit / integration (за замовчуванням) +### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` -- Обсяг: +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped Vitest projects +- Файли: core/unit inventories у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті тести `ui` для Node, охоплені `vitest.unit.config.ts` +- Охоплення: - Чисті unit-тести - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - - Детерміновані регресії для відомих багів + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - Примітка про projects: - - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard watch-цикл непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не сплачує повну ціну запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; правки config/setup, як і раніше, повертаються до широкого повторного запуску root-project. - - Легкі щодо імпорту unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних суто утилітарних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source-файли `plugin-sdk` і `commands` також відображають changed-mode запуски на явні sibling-тести в цих легких lanes, тож редагування helpers не змушує повторно запускати весь важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration-тести і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness для reply із дешевих тестів status/chunk/token. + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати нерелевантні набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, бо цикл watch із кількома shard непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; зміни config/setup усе ще повертаються до широкого повторного запуску root project. + - Легкі unit-тести на імпорт з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних суто утилітарних ділянок маршрутизуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли з важким stateful/runtime залишаються на наявних смугах. + - Окремі helper source files у `plugin-sdk` і `commands` також зіставляють changed-mode runs з явними sibling tests у цих легких смугах, тож зміни helpers не змушують повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі bucket: top-level core helpers, top-level `reply.*` integration tests і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness впливати на дешеві тести status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context для compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime context compaction, зберігайте обидва рівні покриття. - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте в здоровому стані integration-набори embedded runner: + - Також підтримуйте здоровий стан integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction, як і раніше, проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; самих лише helper-тестів недостатньо для заміни цих integration-path. - Примітка про pool: - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live configs. - - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо вам потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидкі локальні ітерації: - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чисто відображаються на менший набір. + - Root UI lane зберігає свій `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 lanes, коли змінені шляхи чисто відповідають меншому набору. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автоматичне локальне масштабування workers тепер навмисно більш консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка про perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту разом із виводом розбивки імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий вид профілювання файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього закоміченого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує main-thread CPU profile для накладних витрат запуску й transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим file parallelism. + - Автомасштабування локальних workers тепер навмисно консервативне і також зменшує навантаження, коли середнє завантаження хоста вже високе, тож кілька паралельних запусків Vitest за замовчуванням шкодять менше. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні changed-mode runs залишалися коректними, коли змінюється тестова обв’язка. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка про налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього зафіксованого diff і виводить wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для накладних витрат запуску та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для unit-набору з вимкненим файловим паралелізмом. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Значення runtime за замовчуванням: - - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). +- Типові параметри runtime: + - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. + - Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням). - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. -- Обсяг: - - End-to-end поведінка multi-instance gateway - - WebSocket/HTTP surfaces, node pairing і важча мережева взаємодія +- Охоплення: + - Поведінка gateway end-to-end з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і важча мережева взаємодія - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли це ввімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для бекенда OpenShell +### E2E: backend smoke OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Обсяг: - - Запускає ізольований gateway OpenShell на хості через Docker +- Охоплення: + - Запускає ізольований OpenShell gateway на хості через Docker - Створює sandbox з тимчасового локального Dockerfile - - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і справний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox + - Потребує локальний CLI `openshell` і працюючий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Обсяг: +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Охоплення: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки rate limit + - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits + - Навмисно не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material до тимчасового test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний home directory. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи bootstrap gateway / Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні startup-логи. -- Ротація API keys (специфічна для провайдера): установіть `*_API_KEYS` у форматі comma/semicolon або `*_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 до тимчасового test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові журнали. +- Ротація API-ключів (залежно від провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож тривалі виклики провайдера залишаються помітно активними, навіть коли захоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. - - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно, що тривалі виклики провайдера активні, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway виводяться одразу під час live-запусків. + - Налаштуйте direct-model heartbeat через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштуйте gateway/probe heartbeat через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запустіть звужений `pnpm test:live` +- Торкаєтесь gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` -## Live: огляд capability Android node +## Live: перевірка можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android node, і перевірити поведінку контракту команди. -- Обсяг: - - Попередньо підготовлений/ручний setup (набір не встановлює/не запускає/не pair-ить застосунок). - - Перевірка gateway `node.invoke` команда за командою для вибраного Android node. -- Обов’язкове попереднє налаштування: - - Android-застосунок уже підключений і pair-ений із gateway. +- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android node, і перевірити поведінку контракту команд. +- Охоплення: + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не спаровує застосунок). + - Перевірка `node.invoke` gateway для кожної команди для вибраного Android node. +- Необхідна попередня підготовка: + - Android-застосунок уже підключено та спарено з gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на capture для capabilities, які ви очікуєте успішно пройти. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke для моделі (profile keys) +## Live: перевірка моделей (ключі профілів) -Live-тести поділено на два шари, щоб ми могли ізолювати збої: +Live-тести поділені на два рівні, щоб можна було ізолювати збої: -- «Direct model» показує, чи взагалі провайдер/модель може відповісти з наданим ключем. +- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. - «Gateway smoke» показує, що повний конвеєр gateway+agent працює для цієї моделі (sessions, history, tools, sandbox policy тощо). -### Шар 1: Direct model completion (без gateway) +### Рівень 1: direct model completion (без 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`, псевдонім для modern), щоб фактично запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався сфокусованим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити 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` — це псевдонім для modern allowlist - - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (comma allowlist) - - Sweeps modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. + - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) + - Modern/all sweep за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. - Як вибирати провайдерів: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: profile store та env fallbacks - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: profile store і резервні варіанти з env + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «provider API зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ невалідний» від «конвеєр gateway agent зламаний» + - Містить невеликі ізольовані регресії (наприклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) -### Шар 2: Gateway + dev agent smoke (що насправді робить "@openclaw") +### Рівень 2: gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/пропатчити session `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по models-with-keys і перевіряти: + - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітерувати моделі-з-ключами й перевіряти: - «змістовну» відповідь (без tools) - - що реальний виклик tool працює (read probe) + - що працює реальний виклик tool (read probe) - необов’язкові додаткові tool probes (exec+read probe) - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати - Деталі probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить agent `read` його та повернути nonce у відповіді. - - `exec+read` probe: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім зчитати його назад через `read`. + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або comma list), щоб звузити набір - - Sweeps modern/all для gateway за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. -- Як вибирати провайдерів (уникайте «OpenRouter everything»): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (comma allowlist) + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Modern/all gateway sweep за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникати «усе від OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Tool + image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (tool stress) - - image probe запускається, коли модель оголошує підтримку введення зображень + - `read` probe + `exec+read` probe (навантаження на tool) + - 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 розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає мультимодальне повідомлення користувача до моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки допускаються) + - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає мультимодальне повідомлення користувача до моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме ви можете протестувати на своїй машині (і точні `provider/model` id), виконайте: +Порада: щоб побачити, що ви можете протестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke для CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: перевірка backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний CLI backend, не торкаючись вашого типового config. -- Типові значення smoke для конкретного backend містяться у визначенні `cli-backend.ts` відповідного extension. +- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашої типової конфігурації. +- Типові smoke-параметри для конкретного backend зберігаються у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Значення за замовчуванням: - - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin відповідного CLI backend. +- Типові значення: + - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих плагіна відповідного backend CLI. - Перевизначення (необов’язково): - `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 args замість вставлення в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання args для зображень, коли задано `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи підставляються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість вставки в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності тієї самої session Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль переключення). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності в одній session Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -318,7 +337,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -329,28 +348,28 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke для CLI-backend всередині Docker-образу репозиторію від імені не-root користувача `node`. -- Він визначає метадані CLI smoke з extension-власника, потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить, що прямий `claude -p` у Docker працює, а потім виконує два ходи Gateway CLI-backend без збереження env vars Anthropic API key. Цей subscription lane за замовчуванням вимикає Claude MCP/tool і image probes, тому що Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів subscription plan. -- Live smoke для CLI-backend тепер перевіряє той самий end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик MCP tool `cron`, перевірений через gateway CLI. -- Типовий smoke для Claude також патчить session із Sonnet на Opus і перевіряє, що відновлена session усе ще пам’ятає попередню нотатку. +- Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke backend CLI всередині образу Docker репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з відповідного extension, а потім встановлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносний OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Ця смуга підписки за замовчуванням вимикає Claude MCP/tool та image probes, тому що Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage, а не через звичайні ліміти плану підписки. +- Live smoke backend CLI тепер перевіряє той самий повний end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик MCP tool `cron`, перевірений через gateway CLI. +- Типовий smoke для Claude також оновлює session із Sonnet на Opus і перевіряє, що відновлена session усе ще пам’ятає попередню нотатку. -## Live: smoke для ACP bind (`/acp spawn ... --bind here`) +## Live: перевірка прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний flow conversation-bind ACP із live ACP agent: +- Мета: перевірити реальний flow conversation-bind ACP з live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation message-channel на місці - - надіслати звичайний follow-up у тій самій conversation - - перевірити, що follow-up потрапляє до транскрипту прив’язаної ACP session + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайне follow-up повідомлення в цій самій розмові + - перевірити, що follow-up потрапляє до transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Значення за замовчуванням: +- Типові значення: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст conversation у стилі Slack DM + - Синтетичний channel: контекст розмови у стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -359,8 +378,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@'` - Примітки: - - Цей lane використовує surface gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agents plugin `acpx` для вибраного ACP harness agent. + - Ця смуга використовує поверхню gateway `chat.send` з адміністративними синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -376,7 +395,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного agent: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -386,31 +405,31 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke для ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind для всіх підтримуваних live CLI agents послідовно: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, підготовлює відповідні auth material 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 vars провайдера з підключеного profile доступними для дочірнього harness CLI. +- Він підключає `~/.profile`, підготовлює відповідні CLI auth material у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підключеного профілю доступними для дочірнього harness CLI. -## Live: smoke для harness app-server Codex +## Live: smoke harness app-server Codex -- Мета: перевірити Codex harness, яким володіє plugin, через звичайний gateway - метод `agent`: - - завантажити bundled plugin `codex` +- Мета: перевірити harness Codex, що належить плагіну, через звичайний метод gateway + `agent`: + - завантажити вбудований плагін `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід до тієї самої session OpenClaw і перевірити, що потік - app-server може відновитися - - запустити `/codex status` і `/codex models` через той самий шлях gateway - command + - надіслати другий хід у ту саму session 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` +- Типова модель: `codex/gpt-5.4` - Необов’язковий 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, плюс необов’язково скопійовані +- Цей smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти, тихо відкотившись до PI. +- Auth: `OPENAI_API_KEY` з shell/profile, плюс за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -433,28 +452,28 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли +- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він підключає змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли auth Codex CLI, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm - prefix, підготовлює source tree, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням вмикає image і MCP/tool probes. Установіть + префікс, підготовлює дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає image і MCP/tool probes. Встановіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли вам потрібен вужчий debug run. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, узгоджено з live - конфігурацією тесту, щоб fallback на `openai-codex/*` або PI не міг приховати регресію - Codex harness. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий запуск для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, що збігається з конфігурацією live + тесту, тож fallback `openai-codex/*` або PI не може приховати регресію + harness Codex. ### Рекомендовані live-рецепти -Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: +Найшвидші й найменш нестабільні — вузькі, явні allowlist: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling через кількох провайдерів: +- Tool calling для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (Gemini API key + Antigravity): @@ -464,19 +483,19 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окремий auth і особливості tooling). +- `google-antigravity/...` використовує міст OAuth Antigravity (agent endpoint у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний binary `gemini`; він має власний auth і може поводитися інакше (streaming/tool support/version skew). + - CLI: OpenClaw виконує локальний бінарник `gemini`; у нього власна auth і він може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «CI model list» (live — це opt-in), але це **рекомендовані** моделі, які слід регулярно покривати на dev machine з ключами. +Немає фіксованого «списку моделей CI» (live — opt-in), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Modern smoke set (tool calling + image) +### Сучасний набір smoke (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -486,12 +505,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запустити gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: tool calling (Read + необов’язковий Exec) +### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на кожну родину провайдерів: +Виберіть щонайменше одну модель для кожної родини провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -502,43 +521,43 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання зображення (attachment → multimodal message) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable variants тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable variants тощо), щоб задіяти image probe. -### Aggregators / alternate gateways +### Агрегатори / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live matrix (якщо у вас є облікові дані/config): +Інші провайдери, які можна включити до live-матриці (якщо у вас є creds/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (користувацькі endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко фіксувати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як це робить CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо live-тест каже «немає creds», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) +- Профілі auth для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «profile keys») - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог legacy state: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile keys) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для окремих агентів, legacy `credentials/` і підтримувані зовнішні CLI auth dirs до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до підготовленого live home, якщо присутній, але це не основне сховище profile-key) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги CLI auth у тимчасовий test home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probes не торкалися вашого реального workspace хоста. -Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` в контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live: Deepgram (транскрипція аудіо) +## Live: Deepgram (транскрибування аудіо) - Тест: `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` @@ -549,31 +568,31 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: media для workflow ComfyUI +## Live: ComfyUI workflow media - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Обсяг: - - Перевіряє bundled шляхи Comfy для зображень, відео і `music_generate` - - Пропускає кожну capability, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у submission workflow Comfy, polling, downloads або реєстрації plugin +- Охоплення: + - Перевіряє вбудовані шляхи comfy image, video і `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації плагіна ## Live: генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` -- Обсяг: - - Перелічує кожен зареєстрований provider plugin для генерації зображень - - Перед probes завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатного auth/profile/model - - Запускає стандартні варіанти генерації зображень через shared runtime capability: +- Охоплення: + - Перелічує кожен зареєстрований плагін провайдера генерації зображень + - Завантажує відсутні env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled провайдери, які охоплюються: +- Поточні вбудовані провайдери в покритті: - `openai` - `google` - Необов’язкове звуження: @@ -588,16 +607,16 @@ 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` -- Обсяг: - - Перевіряє спільний bundled шлях provider-а генерації музики +- Охоплення: + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Перед probes завантажує env vars провайдерів із вашого login shell (`~/.profile`) - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатного auth/profile/model - - Запускає обидва заявлені runtime modes, коли вони доступні: - - `generate` із вхідними даними лише у вигляді prompt + - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` із введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного lane: + - Поточне покриття спільної смуги: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: окремий live-файл Comfy, а не цей спільний sweep @@ -612,26 +631,26 @@ 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` -- Обсяг: - - Перевіряє спільний bundled шлях provider-а генерації відео - - Перед probes завантажує env vars провайдера з вашого login shell (`~/.profile`) - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатного auth/profile/model - - Запускає обидва заявлені runtime modes, коли вони доступні: - - `generate` із вхідними даними лише у вигляді prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає buffer-backed локальне введення зображення в shared sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає buffer-backed локальне введення відео в shared sweep - - Поточні провайдери `imageToVideo`, які оголошені, але пропускаються в shared sweep: - - `vydra`, тому що bundled `veo3` є лише текстовим, а bundled `kling` вимагає remote image URL - - Покриття Vydra, специфічне для провайдера: +- Охоплення: + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` із введенням лише prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення з buffer-backed у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео з buffer-backed у спільному sweep + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: + - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення + - Специфічне покриття Vydra для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture віддаленого image URL + - цей файл запускає `veo3` text-to-video плюс смугу `kling`, яка за замовчуванням використовує fixture віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, які оголошені, але пропускаються в shared sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають reference URLs віддалених `http(s)` / MP4 - - `google`, тому що поточний спільний lane Gemini/Veo використовує локальне buffer-backed введення, а цей шлях не приймається в shared sweep - - `openai`, тому що поточний shared lane не гарантує доступ до org-specific video inpaint/remix + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені референсні URL `http(s)` / MP4 + - `google`, тому що поточна спільна смуга Gemini/Veo використовує локальне введення з buffer-backed, і цей шлях не приймається у спільному sweep + - `openai`, тому що поточна спільна смуга не гарантує доступ на рівні організації до video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` @@ -642,196 +661,195 @@ Live-тести знаходять облікові дані так само, я - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один repo-native entrypoint - - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатний auth - - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один рідний для репозиторію entrypoint + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатні auth + - Повторно використовує `scripts/test-live.mjs`, тож поведінка heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-ранери (необов’язкові перевірки «працює в Linux») +## Docker-раннери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці Docker-раннери поділяються на дві групи: -- Ранери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний config dir і workspace (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live за замовчуванням використовують менший smoke cap, щоб повний Docker sweep залишався практичним: +- Раннери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і підключають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-раннери за замовчуванням використовують менший smoke cap, щоб повний Docker sweep залишався практичним: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, + `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, - `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - вам свідомо потрібне більше вичерпне сканування. -- `test:docker:all` один раз будує live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lanes live. -- Ранери container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або більше реальних контейнерів і перевіряють шляхи інтеграції вищого рівня. + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам навмисно потрібен більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-смуг live. +- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени, не змінюючи auth store хоста: +Docker-раннери live-model також bind-mount лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи auth store на хості: - Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke для ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke для CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke для harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, full scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст channel MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + alias `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Плагіни (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-ранери live-model також bind-mount-ять поточний checkout лише для читання і +Docker-раннери live-model також bind-mount-ять поточний checkout у режимі лише читання і підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але водночас дає змогу запускати Vitest на вашому точному локальному source/config. -Крок staging пропускає великі локальні кеші та результати збирання застосунків, такі як +image компактним, але водночас запускає Vitest точно на вашому локальному source/config. +На етапі підготовки пропускаються великі локальні кеші та виходи збірки застосунків, як-от `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали -реальні workers channel для Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway -live-покриття з цього Docker lane. -`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +реальні workers каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття gateway у цій Docker-смузі. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає контейнер gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, -запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає реальний chat request через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися витягнути -image Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. -Цей lane очікує придатний live model key, і `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його під час Dockerized запусків. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +image Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. +Ця смуга очікує придатний ключ live model, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized runs. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord чи iMessage. Він запускає seeded Gateway -контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення conversation із маршрутизацією, читання transcript, metadata вкладень, -поведінку live event queue, outbound send routing і channel-сповіщення в стилі Claude + -сповіщення про permissions через реальний stdio MCP bridge. Перевірка notifications -напряму аналізує raw stdio MCP frames, тож smoke перевіряє те, що міст -фактично випромінює, а не лише те, що випадково відображає конкретний client SDK. +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального акаунта Telegram, Discord або iMessage. Він піднімає seeded контейнер Gateway, +запускає другий контейнер, який виконує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live events, маршрутизацію вихідного надсилання і сповіщення каналів + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує raw stdio MCP frames, тож smoke перевіряє те, що міст +фактично видає, а не лише те, що випадково показує певний client SDK. -Ручний smoke plain-language thread для ACP (не CI): +Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресій/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні env vars: +Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні CLI auth dirs/files у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - - Каталоги за замовчуванням: `.minimax` - - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібне перевизначення збірки -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів, а не з env +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підключається перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли auth CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів + - Типові каталоги: `.minimax` + - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна нова збірка +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів, а не з env - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag image Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI -## Перевірка документації +## Перевірка коректності документації -Запускайте перевірки документації після змін у документації: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки документації: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли також потрібна перевірка заголовків на сторінці: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Tool calling через gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, примусово записує config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Tool calling gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер gateway (WS `wizard.start`/`wizard.next`, записує config + примусове auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: - Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring session і effects config (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють прив’язку session і вплив config (`src/gateway/gateway.test.ts`). -Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає agent `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/args? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення history сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? +- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок tools, перенесення history session і межі sandbox. Майбутні evals мають насамперед залишатися детермінованими: -- Ранер сценаріїв із mock providers для перевірки tool calls + порядку, читання файлів skill і wiring session. -- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live evals (opt-in, з env-gating) лише після того, як безпечний для CI набір буде готовий. +- Runner сценаріїв із mock-провайдерами для перевірки tool calls + порядку, читання skill-файлів і прив’язки session. +- Невеликий набір сценаріїв, орієнтованих на skill (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live evals (opt-in, із керуванням через env) — лише після того, як безпечний для CI набір буде готовий. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма плагінів і каналів) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму контракту інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають набір -перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +Контрактні тести перевіряють, що кожен зареєстрований плагін і канал відповідає +своєму контракту інтерфейсу. Вони перебирають усі виявлені плагіни й запускають набір +перевірок форми та поведінки. Типова unit-смуга `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо, +коли торкаєтесь спільних поверхонь каналів або провайдерів. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти каналів: `pnpm test:contracts:channels` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` -### Контракти channel +### Контракти каналів Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма плагіна (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки session - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій channel -- **threading** - Обробка ID thread -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групової політики +- **actions** - Обробники дій каналу +- **threading** - Обробка ID потоків +- **directory** - API каталогу/списку учасників +- **group-policy** - Застосування політики груп -### Контракти статусу provider +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probes статусу channel -- **registry** - Форма реєстру plugin +- **status** - Перевірки status каналів +- **registry** - Форма реєстру плагінів -### Контракти provider +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth-choice** - Вибір/селектор auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **discovery** - Виявлення плагінів +- **loader** - Завантаження плагінів +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс плагіна - **wizard** - Майстер налаштування ### Коли запускати -- Після змін у exports або subpaths `plugin-sdk` -- Після додавання або зміни plugin channel чи provider -- Після рефакторингу реєстрації plugin або виявлення +- Після змін exports або subpaths у plugin-sdk +- Після додавання або зміни каналу чи плагіна провайдера +- Після рефакторингу реєстрації або виявлення плагінів -Контрактні тести запускаються в CI і не потребують реальних API keys. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресій (настанови) +## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Віддавайте перевагу найменшому шару, який виявляє баг: - - баг перетворення/відтворення запиту provider → тест direct models - - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить один вибраний target на кожен клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. - - Якщо ви додаєте нову родину target SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується невдачею на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдер або захопіть точне перетворення форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), тримайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому рівню, який виявляє помилку: + - помилка перетворення/повторення запиту провайдера → direct models test + - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Обмеження для обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на кожен клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується з помилкою на некласифікованих target ids, щоб нові класи не могли бути тихо пропущені.