openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-27 17:53:42 +00:00
parent f1b16152b1
commit 24596a472b
1 changed files with 277 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

485
docs/uk/concepts/qa-e2e-automation.md
View File

@ -1,63 +1,63 @@
---
read_when:
- Розуміння того, як поєднується стек QA
- Розуміння того, як стек QA поєднується в єдину систему
- Розширення qa-lab, qa-channel або адаптера транспорту
- Додавання QA-сценаріїв з опорою на репозиторій
- Додавання сценаріїв QA з прив’язкою до репозиторію
- Створення більш реалістичної автоматизації QA навколо панелі керування Gateway
summary: 'Огляд стеку QA: qa-lab, qa-channel, сценарії з опорою на репозиторій, live-канали транспорту, адаптери транспорту та звітність.'
summary: 'Огляд стека QA: qa-lab, qa-channel, сценарії з прив’язкою до репозиторію, лінії живого транспорту, адаптери транспорту та звітність.'
title: Огляд QA
x-i18n:
generated_at: "2026-04-27T17:44:07Z"
generated_at: "2026-04-27T17:51:57Z"
model: gpt-5.4
provider: openai
source_hash: 75c47dc9a430d54c2a701a70efbe098a3ddecef74afe91c4e594f5eea9e57bbb
source_hash: 59d5f32e674cd32a08094b475ba72a70233437d2f8be26a53205628d9770fd6d
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний,
каналоподібний спосіб, ніж це може зробити окремий модульний тест.
Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний,
орієнтований на канали спосіб, ніж це може зробити один модульний тест.
Поточні складові:
- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду,
реакції, редагування та видалення.
- `extensions/qa-lab`: UI налагоджувача та шина QA для спостереження за транскриптом,
ін’єкції вхідних повідомлень і експорту Markdown-звіту.
- `extensions/qa-matrix`, майбутні плагіни-ранери: адаптери live-транспорту, які
керують реальним каналом усередині дочірнього QA Gateway.
- `qa/`: seed-ресурси з опорою на репозиторій для стартового завдання та базових
QA-сценаріїв.
реакцій, редагування та видалення.
- `extensions/qa-lab`: інтерфейс налагодження та шина QA для спостереження за транскриптом,
інʼєкції вхідних повідомлень і експорту звіту у форматі Markdown.
- `extensions/qa-matrix`, майбутні runner-плагіни: адаптери живого транспорту, які
керують реальним каналом усередині дочірнього шлюзу QA.
- `qa/`: seed-ресурси з прив’язкою до репозиторію для стартового завдання та базових
сценаріїв QA.
## Поверхня команд
Усі потоки QA запускаються через `pnpm openclaw qa <subcommand>`. Багато з них мають
псевдоніми скриптів `pnpm qa:*`; підтримуються обидві форми.
аліаси скриптів `pnpm qa:*`; підтримуються обидві форми.
| Команда | Призначення |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Вбудована самоперевірка QA; записує Markdown-звіт. |
| `qa suite` | Запуск сценаріїв з опорою на репозиторій на смузі QA Gateway. Псевдоніми: `pnpm openclaw qa suite --runner multipass` для тимчасової Linux VM. |
| `qa coverage` | Виводить Markdown-інвентар покриття сценаріїв (`--json` для машинного виводу). |
| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує агентний звіт parity-gate. |
| `qa character-eval` | Запускає character QA-сценарій на кількох live-моделях із оціненим звітом. Див. [Звітність](#reporting). |
| `qa manual` | Запускає одноразовий промпт на вибраній смузі провайдера/моделі. |
| `qa ui` | Запускає UI налагоджувача QA та локальну шину QA (псевдонім: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Збирає попередньо підготовлений Docker-образ QA. |
| `qa docker-scaffold` | Записує шаблон docker-compose для панелі керування QA + смуги Gateway. |
| `qa up` | Збирає сайт QA, запускає стек з опорою на Docker, виводить URL (псевдонім: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Запускає лише сервер провайдера AIMock. |
| `qa mock-openai` | Запускає лише сервер провайдера `mock-openai` з урахуванням сценаріїв. |
| `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. |
| `qa matrix` | Смуга live-транспорту з тимчасовим homeserver Tuwunel. Див. [Matrix QA](/uk/concepts/qa-matrix). |
| `qa telegram` | Смуга live-транспорту проти реальної приватної групи Telegram. |
| `qa discord` | Смуга live-транспорту проти реального приватного каналу Discord guild. |
| Команда | Призначення |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Вбудована самоперевірка QA; записує звіт у форматі Markdown. |
| `qa suite` | Запускає сценарії з прив’язкою до репозиторію проти лінії шлюзу QA. Аліаси: `pnpm openclaw qa suite --runner multipass` для тимчасової Linux VM. |
| `qa coverage` | Виводить інвентар покриття сценаріїв у markdown (`--json` для машинного виводу). |
| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує agentic parity-gate звіт. |
| `qa character-eval` | Запускає сценарій character QA на кількох живих моделях з оціненим звітом. Див. [Звітність](#reporting). |
| `qa manual` | Запускає одноразовий prompt проти вибраної лінії provider/model. |
| `qa ui` | Запускає інтерфейс налагодження QA та локальну шину QA (аліас: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Збирає попередньо підготовлений Docker-образ QA. |
| `qa docker-scaffold` | Записує scaffold docker-compose для панелі QA + лінії шлюзу. |
| `qa up` | Збирає сайт QA, запускає стек на базі Docker, виводить URL (аліас: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Запускає лише сервер provider AIMock. |
| `qa mock-openai` | Запускає лише сервер provider `mock-openai`, обізнаний про сценарії. |
| `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. |
| `qa matrix` | Лінія живого транспорту проти тимчасового homeserver Tuwunel. Див. [Matrix QA](/uk/concepts/qa-matrix). |
| `qa telegram` | Лінія живого транспорту проти реальної приватної групи Telegram. |
| `qa discord` | Лінія живого транспорту проти реального каналу Discord guild. |
## Потік роботи оператора
Поточний потік роботи оператора QA — це двопанельний сайт QA:
- Ліворуч: панель керування Gateway (Control UI) з агентом.
- Ліворуч: панель Gateway (Control UI) з агентом.
- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію.
Запустіть його так:
@ -66,12 +66,12 @@ x-i18n:
pnpm qa:lab:up
```
Це збирає сайт QA, запускає смугу Gateway з опорою на Docker і відкриває
сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію,
спостерігати за реальною поведінкою каналу та фіксувати, що спрацювало, що
не спрацювало або що залишилося заблокованим.
Це збирає сайт QA, запускає лінію шлюзу на базі Docker і відкриває
сторінку QA Lab, де оператор або цикл автоматизації може дати агенту
місію QA, спостерігати реальну поведінку каналу та фіксувати, що спрацювало,
що не спрацювало або що залишилося заблокованим.
Для швидшої ітерації UI QA Lab без перебудови Docker-образу щоразу
Для швидшої ітерації інтерфейсу QA Lab без щоразу повторного збирання Docker-образу
запустіть стек із bind-mounted збіркою QA Lab:
```bash
@ -81,125 +81,194 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` тримає Docker-сервіси на попередньо зібраному образі та
bind-mount’ить `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch`
перебудовує цю збірку при змінах, а браузер автоматично перезавантажується,
коли змінюється хеш ресурсу QA Lab.
`qa:lab:up:fast` залишає сервіси Docker на попередньо зібраному образі та bind-mount
монтує `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch`
перезбирає цю збірку при змінах, а браузер автоматично перезавантажується, коли
змінюється хеш ресурсів QA Lab.
Для локального smoke-тесту трасування OpenTelemetry виконайте:
Для локальної smoke-перевірки трасування OpenTelemetry виконайте:
```bash
pnpm qa:otel:smoke
```
Цей скрипт запускає локальний приймач трас OTLP/HTTP, виконує
QA-сценарій `otel-trace-smoke` з увімкненим плагіном `diagnostics-otel`, а потім
декодує експортовані protobuf span-и та перевіряє критичну для релізу форму:
сценарій QA `otel-trace-smoke` з увімкненим плагіном `diagnostics-otel`, а потім
декодує експортовані spans protobuf і перевіряє критично важливу для релізу форму:
мають бути присутні `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled` і `openclaw.message.delivery`;
виклики моделей не повинні експортувати `StreamAbandoned` у разі успішних ходів; сирі діагностичні ID та
атрибути `openclaw.content.*` не повинні потрапляти до трасування. Він записує
`otel-smoke-summary.json` поруч з артефактами QA suite.
атрибути `openclaw.content.*` не повинні потрапляти до траси. Файл
`otel-smoke-summary.json` записується поруч з артефактами набору QA.
Observability QA лишається доступним лише з checkout вихідного коду. npm tarball
навмисно не містить QA Lab, тому смуги релізу пакетів Docker не запускають
команди `qa`. Використовуйте `pnpm qa:otel:smoke` з checkout зібраного вихідного коду
під час змін в інструментуванні діагностики.
Observability QA залишається доступним лише з checkout вихідного коду. У npm tarball навмисно
не включено QA Lab, тому лінії релізу Docker-пакета не запускають команди `qa`. Використовуйте
`pnpm qa:otel:smoke` із checkout зібраного вихідного коду при зміні інструментації
діагностики.
Для transport-real smoke-смуги Matrix виконайте:
Для smoke-лінії Matrix з реальним транспортом виконайте:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
Повний довідник CLI, каталог профілів/сценаріїв, змінні середовища та структура артефактів для цієї смуги наведено в [Matrix QA](/uk/concepts/qa-matrix). Коротко: вона розгортає тимчасовий homeserver Tuwunel у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний плагін Matrix усередині дочірнього QA Gateway, обмеженого цим транспортом (без `qa-channel`), а потім записує Markdown-звіт, JSON-зведення, артефакт observed-events і об’єднаний журнал виводу в `.artifacts/qa-e2e/matrix-<timestamp>/`.
Повний довідник CLI, каталог профілів/сценаріїв, змінні env і структура артефактів для цієї лінії містяться в [Matrix QA](/uk/concepts/qa-matrix). Коротко: вона розгортає тимчасовий homeserver Tuwunel у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний плагін Matrix усередині дочірнього шлюзу QA, обмеженого цим транспортом (без `qa-channel`), а потім записує звіт Markdown, підсумок JSON, артефакт observed-events і обʼєднаний лог виводу до `.artifacts/qa-e2e/matrix-<timestamp>/`.
Для transport-real smoke-смуги Telegram виконайте:
Для smoke-ліній Telegram і Discord з реальним транспортом:
```bash
pnpm openclaw qa telegram
pnpm openclaw qa discord
```
Ця смуга націлюється на одну реальну приватну групу Telegram замість
розгортання тимчасового сервера. Для неї потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також два різні боти в одній
приватній групі. Бот SUT повинен мати ім’я користувача Telegram, а спостереження
bot-to-bot працює найкраще, коли в обох ботів увімкнено режим Bot-to-Bot Communication Mode
у `@BotFather`. Установіть `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`, щоб зберігати
тіла повідомлень в артефактах observed-message (типово вони редагуються).
Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо
вам потрібні артефакти без коду завершення з помилкою.
Звіт і зведення Telegram включають RTT для кожної відповіді — від запиту на
надсилання повідомлення драйвером до спостережуваної відповіді SUT, починаючи з canary.
Обидві орієнтовані на заздалегідь наявний реальний канал із двома ботами (driver + SUT). Обов’язкові змінні env, списки сценаріїв, вихідні артефакти та спільний пул облікових даних Convex задокументовано нижче в розділі [Довідник QA для Telegram і Discord](#telegram-and-discord-qa-reference).
Перед використанням pooled live-облікових даних виконайте:
Перед використанням спільних живих облікових даних виконайте:
```bash
pnpm openclaw qa credentials doctor
```
Doctor перевіряє env брокера Convex, валідує налаштування endpoint і перевіряє
досяжність admin/list, коли присутній секрет супроводжувача. Він повідомляє лише
статус set/missing для секретів.
Doctor перевіряє env брокера Convex, валідовує налаштування endpoint і перевіряє доступність admin/list, коли присутній секрет супровідника. Для секретів він повідомляє лише про стан set/missing.
Для transport-real smoke-смуги Discord виконайте:
## Покриття живого транспорту
```bash
pnpm openclaw qa discord
```
Лінії живого транспорту використовують один контракт, замість того щоб кожна вигадувала власну форму списку сценаріїв. `qa-channel` — це широкий синтетичний набір перевірок поведінки продукту, і він не є частиною матриці покриття живого транспорту.
Ця смуга націлюється на один реальний приватний канал Discord guild із двома ботами: ботом
driver, яким керує harness, і ботом SUT, який запускається дочірнім
OpenClaw Gateway через комплектний плагін Discord. Для неї потрібні
`OPENCLAW_QA_DISCORD_GUILD_ID`, `OPENCLAW_QA_DISCORD_CHANNEL_ID`,
`OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
і `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` у разі використання env-облікових даних. Установіть
`OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`, щоб зберігати тіла повідомлень в
артефактах observed-message (типово вони редагуються).
Смуга перевіряє обробку згадок каналу та перевіряє, що бот SUT
зареєстрував у Discord нативну команду `/help`.
Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо
вам потрібні артефакти без коду завершення з помилкою.
| Лінія | Канарейка | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція треду | Спостереження за реакціями | Команда help | Нативна реєстрація команд |
| -------- | --------- | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | -------------- | -------------------------- | ------------ | ------------------------- |
| Matrix | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | | | | | | | x | |
| Discord | x | x | | | | | | | | x |
## Покриття live-транспорту
Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix,
Telegram і майбутні живі транспорти мають спільний явний контрольний список
контрактів транспорту.
Live-смуги транспорту використовують спільний контракт замість того, щоб кожна вигадувала власну форму списку сценаріїв. `qa-channel` — це широкий синтетичний набір перевірок поведінки продукту, і він не входить до матриці покриття live-транспорту.
| Смуга | Canary | Обмеження за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша взаємодія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | Реєстрація нативної команди |
| -------- | ------ | --------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | --------------------------- |
| Matrix | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | | | | | | | x | |
| Discord | x | x | | | | | | | | x |
Це залишає `qa-channel` широким набором перевірок поведінки продукту, тоді як Matrix,
Telegram і майбутні live-транспорти спільно використовують один явний
контрольний список транспортного контракту.
Для смуги з тимчасовою Linux VM без залучення Docker у шлях QA виконайте:
Для лінії на тимчасовій Linux VM без використання Docker у шляху QA виконайте:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Це завантажує новий гість Multipass, установлює залежності, збирає OpenClaw
усередині гостя, запускає `qa suite`, а потім копіює звичайний QA-звіт і
зведення назад до `.artifacts/qa-e2e/...` на хості.
Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості.
Запуски suite на хості й у Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно
з ізольованими worker-ами Gateway. `qa-channel` за замовчуванням використовує рівень паралелізму 4,
обмежений кількістю вибраних сценаріїв. Використовуйте `--concurrency <count>`, щоб налаштувати
кількість worker-ів, або `--concurrency 1` для послідовного виконання.
Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо
Це завантажує нову гостьову систему Multipass, встановлює залежності, збирає OpenClaw
усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт і
підсумок QA назад у `.artifacts/qa-e2e/...` на хості.
Використовується така сама поведінка вибору сценаріїв, як і в `qa suite` на хості.
Запуски наборів на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно
з ізольованими worker-процесами шлюзу. Для `qa-channel` за замовчуванням використовується concurrency
4, обмежене кількістю вибраних сценаріїв. Використовуйте `--concurrency <count>`, щоб налаштувати
кількість worker-процесів, або `--concurrency 1` для послідовного виконання.
Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли
вам потрібні артефакти без коду завершення з помилкою.
Live-запуски передають підтримувані QA-входи автентифікації, які практичні для
гостьової системи: ключі провайдерів на основі env, шлях до конфігурації QA live provider і
Живі запуски передають підтримувані вхідні дані автентифікації QA, які практичні для
гостя: ключі provider на основі env, шлях до конфігурації живого provider QA і
`CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість
міг записувати назад через змонтований робочий простір.
міг записувати дані назад через змонтований workspace.
## Seed-ресурси з опорою на репозиторій
## Довідник QA для Telegram і Discord
Seed-ресурси розміщені в `qa/`:
Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і розгортання homeserver на базі Docker. Telegram і Discord менші — лише кілька сценаріїв у кожному, без системи профілів, проти вже наявних реальних каналів — тому їхній довідник міститься тут.
### Спільні прапорці CLI
Обидві лінії реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають однакові прапорці:
| Прапорець | За замовчуванням | Опис |
| ------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Запустити лише цей сценарій. Можна вказувати повторно. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord}-<timestamp>` | Куди записуються звіти/підсумок/спостережені повідомлення та журнал виводу. Відносні шляхи обчислюються від `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. |
| `--sut-account <id>` | `sut` | Ідентифікатор тимчасового облікового запису всередині конфігурації шлюзу QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` також працює). |
| `--model <ref>` / `--alt-model <ref>` | provider default | Посилання на основну/альтернативну модель. |
| `--fast` | вимкнено | Швидкий режим provider там, де він підтримується. |
| `--credential-source <env\|convex>` | `env` | Див. [Спільний пул облікових даних Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` у CI, інакше `maintainer` | Роль, що використовується з `--credential-source convex`. |
Обидві команди завершуються з ненульовим кодом у разі помилки будь-якого сценарію. `--allow-failures` записує артефакти без встановлення коду завершення з помилкою.
### Telegram QA
```bash
pnpm openclaw qa telegram
```
Націлено на одну реальну приватну групу Telegram із двома різними ботами (driver + SUT). Бот SUT повинен мати ім’я користувача Telegram; спостереження бот-до-бота працює найкраще, коли в обох ботів увімкнено **Bot-to-Bot Communication Mode** у `@BotFather`.
Обов’язкові змінні env при `--credential-source env`:
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий ідентифікатор чату (рядок).
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
Необов’язково:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах observed-message (за замовчуванням вони редагуються).
Сценарії (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
- `telegram-canary`
- `telegram-mention-gating`
- `telegram-mentioned-message-reply`
- `telegram-help-command`
- `telegram-commands-command`
- `telegram-tools-compact-command`
- `telegram-whoami-command`
- `telegram-context-command`
Вихідні артефакти:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — містить RTT для кожної відповіді (надсилання driver → спостережена відповідь SUT), починаючи з canary.
- `telegram-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### Discord QA
```bash
pnpm openclaw qa discord
```
Націлено на один реальний приватний канал Discord guild із двома ботами: ботом driver, яким керує harness, і ботом SUT, що запускається дочірнім шлюзом OpenClaw через вбудований плагін Discord. Перевіряє обробку згадок у каналі та те, що бот SUT зареєстрував нативну команду `/help` у Discord.
Обов’язкові змінні env при `--credential-source env`:
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — має збігатися з ідентифікатором користувача бота SUT, повернутим Discord (інакше лінія швидко завершиться з помилкою).
Необов’язково:
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах observed-message.
Сценарії (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`):
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
Вихідні артефакти:
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
### Спільний пул облікових даних Convex
І лінії Telegram, і лінії Discord можуть орендувати облікові дані зі спільного пулу Convex замість читання наведених вище змінних env. Передайте `--credential-source convex` (або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, надсилає Heartbeat протягом усього запуску та звільняє її під час завершення роботи. Види пулів — `"telegram"` і `"discord"`.
Форми payload, які брокер валідовує на `admin/add`:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` має бути рядком із числовим chat-id.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
Операційні змінні env і контракт endpoint брокера Convex описані в [Testing → Shared Telegram credentials via Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу передує підтримці Discord; семантика брокера однакова для обох видів).
## Seeds із прив’язкою до репозиторію
Seed-ресурси містяться в `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
@ -207,113 +276,113 @@ Seed-ресурси розміщені в `qa/`:
Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і
агенту.
`qa-lab` має залишатися універсальним markdown-ранером. Кожен markdown-файл сценарію є
джерелом істини для одного тестового запуску і має визначати:
`qa-lab` має залишатися універсальним markdown-runner. Кожен markdown-файл сценарію
є джерелом істини для одного тестового запуску й повинен визначати:
- метадані сценарію
- необов’язкові метадані категорії, можливостей, смуги та ризику
- посилання на документацію та код
- необов’язкові вимоги до плагінів
- необов’язковий patch конфігурації Gateway
- необов’язкові метадані category, capability, lane та risk
- посилання на docs і code
- необов’язкові вимоги до Plugin
- необов’язковий патч конфігурації шлюзу
- виконуваний `qa-flow`
Універсальна поверхня рантайму, що підтримує `qa-flow`, може залишатися загальною
і наскрізною. Наприклад, markdown-сценарії можуть поєднувати допоміжні засоби з боку
транспорту з допоміжними засобами з боку браузера, які керують вбудованим Control UI через
інтерфейс Gateway `browser.request`, без додавання спеціального раннера.
Багаторазова runtime-поверхня, що підтримує `qa-flow`, може залишатися універсальною
і наскрізною. Наприклад, markdown-сценарії можуть поєднувати допоміжні
засоби на боці транспорту з допоміжними засобами на боці браузера, які керують вбудованим Control UI через
шов Gateway `browser.request`, не додаючи спеціалізований runner.
Файли сценаріїв слід групувати за можливостями продукту, а не за папкою дерева
вихідного коду. Зберігайте стабільність ID сценаріїв під час переміщення файлів; використовуйте
`docsRefs` і `codeRefs` для відстежуваності реалізації.
Файли сценаріїв слід групувати за можливостями продукту, а не за папкою
дерева вихідного коду. Зберігайте стабільність ідентифікаторів сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs`
для трасування реалізації.
Базовий список має залишатися достатньо широким, щоб покривати:
Базовий список має залишатися достатньо широким, щоб охоплювати:
- DM і чат у каналі
- чат у DM і каналі
- поведінку тредів
- життєвий цикл дій із повідомленнями
- Cron callbacks
- виклик пам’яті
- зворотні виклики Cron
- пригадування пам’яті
- перемикання моделей
- передавання до subagent
- передачу до субагента
- читання репозиторію та документації
- одне невелике завдання зі збірки, наприклад Lobster Invaders
- одне невелике завдання зі збирання, наприклад Lobster Invaders
## Смуги mock-провайдерів
## Mock-лінії provider
`qa suite` має дві локальні смуги mock-провайдерів:
`qa suite` має дві локальні mock-лінії provider:
- `mock-openai` — це mock OpenClaw з урахуванням сценаріїв. Він залишається
типовою детермінованою mock-смугою для QA з опорою на репозиторій і parity gate.
- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколу,
фікстур, запису/відтворення та chaos. Він є додатковим і не
замінює диспетчер сценаріїв `mock-openai`.
- `mock-openai` — це mock OpenClaw, обізнаний про сценарії. Він залишається
типовою детермінованою mock-лінією для QA з прив’язкою до репозиторію та parity gate.
- `aimock` запускає сервер provider на базі AIMock для експериментального
покриття протоколів, фікстур, запису/відтворення та chaos-перевірок. Це доповнення і воно не
замінює dispatcher сценаріїв `mock-openai`.
Реалізація смуг провайдера знаходиться в `extensions/qa-lab/src/providers/`.
Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделі Gateway,
потребами staging auth-profile та прапорцями можливостей live/mock. Спільний код suite і
Gateway має маршрутизувати через реєстр провайдерів замість розгалуження за
іменами провайдерів.
Реалізація provider-ліній міститься в `extensions/qa-lab/src/providers/`.
Кожен provider володіє своїми значеннями за замовчуванням, запуском локального сервера, конфігурацією моделі шлюзу,
потребами staging auth-profile і прапорцями можливостей live/mock. Спільний код suite і
шлюзу має маршрутизуватися через реєстр provider, а не розгалужуватися за
іменами provider.
## Адаптери транспорту
`qa-lab` володіє універсальним інтерфейсом транспорту для markdown QA-сценаріїв. `qa-channel` — перший адаптер на цьому інтерфейсі, але ціль архітектури ширша: майбутні реальні або синтетичні канали мають підключатися до того самого раннера suite замість додавання transport-specific QA-ранера.
`qa-lab` володіє універсальним швом транспорту для markdown-сценаріїв QA. `qa-channel` — перший адаптер на цьому шві, але ціль дизайну ширша: майбутні реальні або синтетичні канали мають підключатися до того самого runner наборів замість додавання transport-specific runner QA.
На рівні архітектури розподіл такий:
- `qa-lab` володіє універсальним виконанням сценаріїв, паралельністю worker-ів, записом артефактів і звітністю.
- Адаптер транспорту володіє конфігурацією Gateway, готовністю, спостереженням за вхідними й вихідними подіями, транспортними діями та нормалізованим станом транспорту.
- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає універсальну поверхню рантайму, яка їх виконує.
- `qa-lab` володіє універсальним виконанням сценаріїв, concurrency worker-процесів, записом артефактів і звітністю.
- Адаптер транспорту володіє конфігурацією шлюзу, готовністю, спостереженням за вхідними й вихідними подіями, діями транспорту та нормалізованим станом транспорту.
- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову runtime-поверхню, яка їх виконує.
### Додавання каналу
Додавання каналу до markdown-системи QA вимагає рівно двох речей:
1. Адаптера транспорту для каналу.
2. Пакета сценаріїв, який перевіряє контракт каналу.
1. Адаптер транспорту для каналу.
2. Набір сценаріїв, що перевіряє контракт каналу.
Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може володіти цим потоком.
`qa-lab` володіє спільною механікою хоста:
- коренем команди `openclaw qa`
- запуском і зупинкою suite
- паралельністю worker-ів
- запуском і завершенням набору
- concurrency worker-процесів
- записом артефактів
- генерацією звітів
- виконанням сценаріїв
- псевдонімами сумісності для старіших сценаріїв `qa-channel`
- аліасами сумісності для старіших сценаріїв `qa-channel`
Плагіни-ранери володіють транспортним контрактом:
Runner-плагіни володіють транспортним контрактом:
- тим, як `openclaw qa <runner>` монтується під спільним коренем `qa`
- тим, як Gateway конфігурується для цього транспорту
- тим, як перевіряється готовність
- тим, як ін’єктуються вхідні події
- тим, як спостерігаються вихідні повідомлення
- тим, як надаються транскрипти й нормалізований стан транспорту
- тим, як виконуються дії з опорою на транспорт
- тим, як обробляються transport-specific скидання або очищення
- як `openclaw qa <runner>` монтується під спільним коренем `qa`
- як шлюз налаштовується для цього транспорту
- як перевіряється готовність
- як інʼєктуються вхідні події
- як спостерігаються вихідні повідомлення
- як надаються транскрипти та нормалізований стан транспорту
- як виконуються дії на основі транспорту
- як обробляється transport-specific скидання або очищення
Мінімальна планка впровадження для нового каналу:
Мінімальний поріг прийняття для нового каналу:
1. Залишайте `qa-lab` власником спільного кореня `qa`.
2. Реалізуйте транспортний раннер на спільному інтерфейсі хоста `qa-lab`.
3. Тримайте transport-specific механіку всередині плагіна-ранера або harness каналу.
4. Монтуйте раннер як `openclaw qa <runner>` замість реєстрації конкуруючої кореневої команди. Плагіни-ранери мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і раннера має залишатися за окремими entrypoint.
1. Залиште `qa-lab` власником спільного кореня `qa`.
2. Реалізуйте transport runner на спільному хостовому шві `qa-lab`.
3. Тримайте transport-specific механіку всередині runner-плагіна або harness каналу.
4. Монтуйте runner як `openclaw qa <runner>`, а не реєструйте конкуруючий кореневий простір команд. Runner-плагіни мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint.
5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`.
6. Використовуйте універсальні helper-и сценаріїв для нових сценаріїв.
7. Зберігайте роботу наявних псевдонімів сумісності, якщо в репозиторії не виконується навмисна міграція.
6. Використовуйте універсальні helper для нових сценаріїв.
7. Зберігайте роботу наявних аліасів сумісності, якщо тільки репозиторій не виконує навмисну міграцію.
Правило прийняття рішення суворе:
Правило ухвалення рішення суворе:
- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`.
- Якщо поведінка залежить від одного канального транспорту, тримайте її в цьому плагіні-ранері або harness плагіна.
- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додавайте універсальний helper замість channel-specific гілки в `suite.ts`.
- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію.
- Якщо поведінка залежить від транспорту одного каналу, тримайте її в цьому runner-плагіні або harness плагіна.
- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте універсальний helper замість branch для конкретного каналу в `suite.ts`.
- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію.
### Назви helper-ів сценаріїв
### Назви helper сценаріїв
Бажані універсальні helper-и для нових сценаріїв:
Переважні універсальні helper для нових сценаріїв:
- `waitForTransportReady`
- `waitForChannelReady`
@ -328,22 +397,22 @@ Gateway має маршрутизувати через реєстр провай
- `formatTransportTranscript`
- `resetTransport`
Псевдоніми сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але для створення нових сценаріїв слід використовувати універсальні назви. Ці псевдоніми існують, щоб уникнути міграції в один день, а не як модель на майбутнє.
Аліаси сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але для створення нових сценаріїв слід використовувати універсальні назви. Аліаси існують, щоб уникнути міграції в один день, а не як модель на майбутнє.
## Звітність
`qa-lab` експортує Markdown-протокольний звіт зі спостережуваної часової шкали шини.
Звіт має відповідати на запитання:
`qa-lab` експортує протокольний звіт Markdown зі спостережуваної часової шкали шини.
Звіт має відповідати на такі запитання:
- Що спрацювало
- Що не спрацювало
- Що залишилося заблокованим
- Які подальші сценарії варто додати
- Які follow-up сценарії варто додати
Щоб отримати інвентар доступних сценаріїв — корисний під час оцінки подальшої роботи або підключення нового транспорту — виконайте `pnpm openclaw qa coverage` (додайте `--json` для машинозчитуваного виводу).
Щоб отримати інвентар доступних сценаріїв — корисний під час оцінювання обсягу подальших робіт або підключення нового транспорту — виконайте `pnpm openclaw qa coverage` (додайте `--json` для машинозчитуваного виводу).
Для перевірок характеру та стилю запускайте той самий сценарій на кількох refs live-моделей
і записуйте оцінений Markdown-звіт:
Для перевірок характеру та стилю запустіть той самий сценарій на кількох живих
посиланнях моделей і запишіть оцінений звіт у форматі Markdown:
```bash
pnpm openclaw qa character-eval \
@ -362,41 +431,41 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
Команда запускає локальні дочірні процеси QA Gateway, а не Docker. Сценарії character eval
мають задавати persona через `SOUL.md`, а потім виконувати звичайні користувацькі ходи,
такі як чат, допомога з робочим простором і невеликі файлові завдання. Моделі-кандидату
Команда запускає локальні дочірні процеси шлюзу QA, а не Docker. Сценарії character eval
мають задавати persona через `SOUL.md`, а потім виконувати звичайні ходи користувача,
такі як чат, допомога з workspace і невеликі файлові завдання. Кандидатній моделі
не слід повідомляти, що її оцінюють. Команда зберігає кожен повний
транскрипт, записує базову статистику запуску, а потім просить моделі-судді в fast mode з
міркуванням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором.
Використовуйте `--blind-judge-models` при порівнянні провайдерів: prompt судді однаково отримує
кожен транскрипт і статус запуску, але refs кандидатів замінюються нейтральними
мітками на кшталт `candidate-01`; після парсингу звіт зіставляє ранги назад із реальними refs.
Для запусків кандидатів за замовчуванням використовується thinking `high`, `medium` для GPT-5.5 і `xhigh`
для старіших eval refs OpenAI, які це підтримують. Замініть значення для конкретного кандидата прямо в рядку через
транскрипт, записує базову статистику запуску, а потім просить моделі-оцінювачі в швидкому режимі з
мисленням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором.
Використовуйте `--blind-judge-models` при порівнянні provider: prompt оцінювання все одно отримує
кожен транскрипт і статус запуску, але посилання кандидатів замінюються нейтральними
мітками на кшталт `candidate-01`; після парсингу звіт зіставляє ранжування назад із реальними посиланнями.
Для кандидатних запусків за замовчуванням використовується мислення `high`, з `medium` для GPT-5.5 і `xhigh`
для старіших посилань OpenAI eval, які це підтримують. Перевизначте конкретного кандидата безпосередньо через
`--model provider/model,thinking=<level>`. `--thinking <level>` як і раніше задає
глобальне резервне значення, а старіша форма `--model-thinking <provider/model=level>` зберігається
глобальний резервний варіант, а старіша форма `--model-thinking <provider/model=level>` зберігається
для сумісності.
Refs кандидатів OpenAI за замовчуванням використовують fast mode, щоб застосовувалася пріоритетна обробка там,
де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` прямо в рядку, коли
одному кандидату або судді потрібно перевизначення. Передавайте `--fast` лише тоді, коли хочете
примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість роботи кандидатів і суддів
записується у звіті для аналізу бенчмарків, але в prompt-ах для суддів явно сказано
Для посилань кандидатів OpenAI за замовчуванням використовується швидкий режим, щоб застосовувалася
обробка з пріоритетом там, де provider це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` безпосередньо, коли
окремому кандидату або оцінювачу потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете
примусово ввімкнути швидкий режим для кожної кандидатної моделі. Тривалість роботи кандидатів і оцінювачів
записується у звіті для аналізу бенчмарків, але prompts оцінювання явно вказують
не ранжувати за швидкістю.
Запуски моделей-кандидатів і моделей-суддів за замовчуванням обидва мають паралельність 16. Зменшуйте
`--concurrency` або `--judge-concurrency`, коли обмеження провайдера або навантаження на локальний Gateway
І для кандидатних, і для суддівських запусків моделей за замовчуванням використовується concurrency 16. Зменшуйте
`--concurrency` або `--judge-concurrency`, коли обмеження provider або навантаження на локальний шлюз
роблять запуск надто шумним.
Якщо не передано жодного кандидатського `--model`, для character eval за замовчуванням використовуються
Якщо не передано жодного кандидатного `--model`, для character eval за замовчуванням використовуються
`openai/gpt-5.5`, `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.5,thinking=xhigh,fast` і
`anthropic/claude-opus-4-6,thinking=high`.
## Пов’язана документація
## Пов’язані документи
- [Matrix QA](/uk/concepts/qa-matrix)
- [QA Channel](/uk/channels/qa-channel)
- [Testing](/uk/help/testing)
- [Dashboard](/uk/web/dashboard)
- [Канал QA](/uk/channels/qa-channel)
- [Тестування](/uk/help/testing)
- [Панель керування](/uk/web/dashboard)