diff --git a/docs/uk/cli/crestodian.md b/docs/uk/cli/crestodian.md index caf9c621a..aee1f39e7 100644 --- a/docs/uk/cli/crestodian.md +++ b/docs/uk/cli/crestodian.md @@ -1,15 +1,15 @@ --- read_when: - - Ви запускаєте openclaw без команди й хочете зрозуміти Crestodian - - Вам потрібен безпечний спосіб без конфігурації, щоб перевірити або відновити OpenClaw - - Ви проєктуєте або вмикаєте режим відновлення каналу повідомлень -summary: Довідник CLI та модель безпеки для Crestodian, помічника з налаштування й відновлення без конфігурації та з безпечними значеннями за замовчуванням + - Ви запускаєте openclaw без команди та хочете зрозуміти, що таке Crestodian + - Вам потрібен безконфігураційно-безпечний спосіб перевірити або відновити OpenClaw + - Ви проєктуєте або вмикаєте режим відновлення для каналу повідомлень +summary: Довідка CLI та модель безпеки для Crestodian, безконфігураційно-безпечного інструмента налаштування та відновлення title: Crestodian x-i18n: - generated_at: "2026-04-25T11:56:36Z" + generated_at: "2026-04-25T12:18:26Z" model: gpt-5.4 provider: openai - source_hash: 4857fccfc3d5c35c0a05c47d8c2276b828484b9a0a2030447a31072c2a13b4f5 + source_hash: ebcd6a72f78134fa572a85acc6c2f0381747a27fd6be84269c273390300bb533 source_path: cli/crestodian.md workflow: 15 --- @@ -17,35 +17,35 @@ x-i18n: # `openclaw crestodian` Crestodian — це локальний помічник OpenClaw для налаштування, відновлення та конфігурації. Його -спроєктовано так, щоб він залишався доступним, коли звичайний шлях агента зламаний. +спроєктовано так, щоб він залишався доступним, коли звичайний шлях агента зламано. -Запуск `openclaw` без команди запускає Crestodian в інтерактивному терміналі. +Запуск `openclaw` без команди відкриває Crestodian в інтерактивному терміналі. Запуск `openclaw crestodian` явно запускає того самого помічника. ## Що показує Crestodian -Під час запуску інтерактивний Crestodian відкриває ту саму оболонку TUI, що й +Під час запуску інтерактивний Crestodian відкриває ту саму оболонку TUI, що використовується в `openclaw tui`, але з чат-бекендом Crestodian. Журнал чату починається з короткого привітання: - коли слід запускати Crestodian -- яку модель або який шлях детермінованого планувальника Crestodian фактично використовує +- яку модель або шлях детерміністичного планувальника Crestodian фактично використовує - валідність конфігурації та агента за замовчуванням -- доступність Gateway з першої перевірки під час запуску +- доступність Gateway із першої перевірки під час запуску - наступну дію з налагодження, яку Crestodian може виконати -Він не виводить секрети та не завантажує команди CLI Plugin лише для запуску. TUI -усе одно надає звичайний заголовок, журнал чату, рядок стану, нижній колонтитул, автодоповнення +Він не виводить секрети й не завантажує CLI-команди Plugin лише для запуску. TUI +усе ще надає звичайний заголовок, журнал чату, рядок стану, нижній колонтитул, автодоповнення та елементи керування редактором. Використовуйте `status` для детального переліку з шляхом до конфігурації, шляхами до docs/source, -локальними перевірками CLI, наявністю API-ключів, агентами, моделлю та відомостями про Gateway. +локальними CLI-перевірками, наявністю API-ключів, агентами, моделлю та відомостями про Gateway. -Crestodian використовує те саме виявлення довідкових матеріалів OpenClaw, що й звичайні агенти. У Git checkout -він спрямовує себе на локальний `docs/` і локальне дерево source. В установленому npm package він -використовує docs із комплекту package і посилається на +Crestodian використовує той самий механізм виявлення довідкових матеріалів OpenClaw, що й звичайні агенти. У Git checkout +він спрямовує себе на локальні `docs/` і локальне дерево вихідного коду. У разі встановлення npm package він +використовує docs із комплекту пакета та посилається на [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw), з явною -рекомендацією переглядати source, коли docs недостатньо. +рекомендацією переглянути вихідний код, якщо docs недостатньо. ## Приклади @@ -90,13 +90,13 @@ quit - `openclaw.json` відсутній - `openclaw.json` невалідний -- Gateway недоступний +- Gateway не працює - реєстрація команд Plugin недоступна - ще не налаштовано жодного агента -`openclaw --help` і `openclaw --version` як і раніше використовують звичайні швидкі шляхи. -Неінтерактивний `openclaw` завершує роботу з коротким повідомленням замість виведення кореневої -довідки, оскільки продукт без команди — це Crestodian. +`openclaw --help` і `openclaw --version` усе ще використовують звичайні швидкі шляхи. +Неінтерактивний `openclaw` завершується коротким повідомленням замість виведення довідки +верхнього рівня, оскільки продуктом без команди є Crestodian. ## Операції та підтвердження @@ -107,23 +107,23 @@ Crestodian використовує типізовані операції зам - показати огляд - перелічити агентів - показати стан моделі/бекенда -- виконати перевірки `status` або `health` +- запустити перевірки status або health - перевірити доступність Gateway -- запустити `doctor` без інтерактивних виправлень -- перевірити конфігурацію +- запустити doctor без інтерактивних виправлень +- validate config - показати шлях до журналу аудиту -Операції зі збереженням змін вимагають підтвердження в розмові в інтерактивному режимі, якщо +Постійні операції потребують підтвердження в розмові в інтерактивному режимі, якщо ви не передасте `--yes` для прямої команди: - записати конфігурацію -- виконати `config set` -- встановити підтримувані значення SecretRef через `config set-ref` -- запустити bootstrap налаштування/онбордингу +- запустити `config set` +- задати підтримувані значення SecretRef через `config set-ref` +- запустити bootstrap налаштування/onboarding - змінити модель за замовчуванням - запустити, зупинити або перезапустити Gateway - створити агентів -- виконати виправлення doctor, які переписують конфігурацію або стан +- запустити виправлення doctor, які переписують конфігурацію або стан Застосовані записи фіксуються в: @@ -131,14 +131,14 @@ Crestodian використовує типізовані операції зам ~/.openclaw/audit/crestodian.jsonl ``` -Виявлення не аудитується. У журнал потрапляють лише застосовані операції та записи. +Виявлення не аудитується. Журналюються лише застосовані операції та записи. -`openclaw onboard --modern` запускає Crestodian як modern preview онбордингу. -Звичайний `openclaw onboard` як і раніше запускає classic onboarding. +`openclaw onboard --modern` запускає Crestodian як modern preview для onboarding. +Звичайний `openclaw onboard` усе ще запускає classic onboarding. ## Bootstrap налаштування -`setup` — це bootstrap онбордингу з пріоритетом чату. Він записує зміни лише через типізовані +`setup` — це bootstrap onboarding у стилі чату. Він записує дані лише через типізовані операції конфігурації та спочатку запитує підтвердження. ```text @@ -147,43 +147,43 @@ setup workspace ~/Projects/work setup workspace ~/Projects/work model openai/gpt-5.5 ``` -Коли модель не налаштована, setup вибирає перший придатний бекенд у такому -порядку та повідомляє, що саме він вибрав: +Якщо модель не налаштована, setup вибирає перший придатний бекенд у такому +порядку й повідомляє, що саме він вибрав: -- наявна явно задана модель, якщо вже налаштована +- наявна явно задана модель, якщо її вже налаштовано - `OPENAI_API_KEY` -> `openai/gpt-5.5` - `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7` - Claude Code CLI -> `claude-cli/claude-opus-4-7` - Codex CLI -> `codex-cli/gpt-5.5` -Якщо нічого не доступно, setup все одно записує робочий простір за замовчуванням і залишає -модель невстановленою. Установіть або виконайте вхід у Codex/Claude Code, або надайте -`OPENAI_API_KEY`/`ANTHROPIC_API_KEY`, а потім знову запустіть setup. +Якщо жоден варіант недоступний, setup усе одно записує workspace за замовчуванням і залишає +модель незаданою. Установіть або виконайте вхід у Codex/Claude Code, або зробіть +`OPENAI_API_KEY`/`ANTHROPIC_API_KEY` доступними, а потім знову запустіть setup. -## Model-Assisted Planner +## Планувальник із підтримкою моделі -Crestodian завжди запускається в детермінованому режимі. Для нечітких команд, які -детермінований парсер не розуміє, локальний Crestodian може виконати один обмежений -хід планувальника через звичайні runtime-шляхи OpenClaw. Спочатку він використовує +Crestodian завжди запускається в детерміністичному режимі. Для нечітких команд, які +детерміністичний парсер не розуміє, локальний Crestodian може виконати один обмежений +хід планувальника через звичайні шляхи виконання OpenClaw. Спочатку він використовує налаштовану модель OpenClaw. Якщо жодна налаштована модель ще не придатна до використання, -він може перейти до локальних runtime, уже наявних на машині: +він може повернутися до локальних середовищ виконання, які вже наявні на машині: - Claude Code CLI: `claude-cli/claude-opus-4-7` -- harness app-server Codex: `openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` +- Codex app-server harness: `openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` - Codex CLI: `codex-cli/gpt-5.5` -Model-Assisted Planner не може безпосередньо змінювати конфігурацію. Він має перетворити -запит на одну з типізованих команд Crestodian, після чого застосовуються звичайні правила -підтвердження й аудиту. Crestodian виводить модель, яку він використав, і інтерпретовану -команду перед виконанням будь-яких дій. Резервні ходи планувальника без конфігурації є -тимчасовими, виконуються без інструментів там, де це підтримує runtime, і використовують -тимчасовий робочий простір/сеанс. +Планувальник із підтримкою моделі не може безпосередньо змінювати конфігурацію. Він має +перекласти запит в одну з типізованих команд Crestodian, після чого застосовуються +звичайні правила підтвердження й аудиту. Crestodian виводить модель, яку він використав, +і інтерпретовану команду перед виконанням будь-яких дій. Резервні ходи планувальника +в безконфігураційному режимі є тимчасовими, без інструментів там, де це підтримує середовище виконання, +і використовують тимчасовий workspace/session. -Режим відновлення каналу повідомлень не використовує Model-Assisted Planner. Віддалене -відновлення залишається детермінованим, щоб зламаний або скомпрометований звичайний шлях агента +Режим відновлення каналу повідомлень не використовує планувальник із підтримкою моделі. Віддалене +відновлення залишається детерміністичним, щоб зламаний або скомпрометований звичайний шлях агента не можна було використати як редактор конфігурації. -## Перемикання до агента +## Перемикання на агента Використовуйте селектор природною мовою, щоб вийти з Crestodian і відкрити звичайний TUI: @@ -193,30 +193,30 @@ talk to work agent switch to main agent ``` -`openclaw tui`, `openclaw chat` і `openclaw terminal` як і раніше безпосередньо відкривають -звичайний TUI агента. Вони не запускають Crestodian. +`openclaw tui`, `openclaw chat` і `openclaw terminal` усе ще безпосередньо відкривають звичайний +TUI агента. Вони не запускають Crestodian. -Після переходу до звичайного TUI використовуйте `/crestodian`, щоб повернутися до Crestodian. -Ви можете додати подальший запит: +Після перемикання до звичайного TUI використайте `/crestodian`, щоб повернутися до Crestodian. +Ви можете додати наступний запит: ```text /crestodian /crestodian restart gateway ``` -Перемикання агента в межах TUI залишає підказку, що `/crestodian` доступний. +Перемикання агентів у межах TUI залишає підказку, що `/crestodian` доступний. ## Режим відновлення повідомлень -Режим відновлення повідомлень — це точка входу Crestodian для каналу повідомлень. Він призначений -для випадків, коли ваш звичайний агент недоступний, але довірений канал, такий як WhatsApp, -усе ще приймає команди. +Режим відновлення повідомлень — це точка входу до Crestodian через канал повідомлень. Він призначений для +випадку, коли ваш звичайний агент не працює, але довірений канал, такий як WhatsApp, +усе ще отримує команди. Підтримувана текстова команда: - `/crestodian ` -Потік дій оператора: +Потік для оператора: ```text You, in a trusted owner DM: /crestodian status @@ -234,28 +234,29 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5 /crestodian create agent work workspace ~/Projects/work ``` -Віддалений режим відновлення — це адміністративна поверхня. До нього слід ставитися як до +Віддалений режим відновлення — це поверхня адміністрування. До нього слід ставитися як до віддаленого відновлення конфігурації, а не як до звичайного чату. Контракт безпеки для віддаленого відновлення: -- Вимкнено, коли активне sandboxing. Якщо агент/сеанс працює в sandbox, - Crestodian має відмовити у віддаленому відновленні та пояснити, що потрібне локальне відновлення через CLI. +- Вимкнено, коли активне sandboxing. Якщо агент/session працює в sandbox, + Crestodian має відмовити у віддаленому відновленні й пояснити, що потрібне локальне відновлення через CLI. - Ефективний стан за замовчуванням — `auto`: дозволяти віддалене відновлення лише в довіреному режимі YOLO, - де runtime вже має локальні повноваження без sandbox. -- Вимагати явної ідентичності власника. Відновлення не повинно приймати правила відправника з wildcard, - відкриту політику груп, неавтентифіковані Webhook або анонімні канали. -- За замовчуванням — лише owner DM. Відновлення в групі/каналі вимагає явного opt-in і - все одно має спрямовувати запити на підтвердження до owner DM. -- Віддалене відновлення не може відкрити локальний TUI або перемкнутися в інтерактивний сеанс агента. - Для передачі керування агенту використовуйте локальний `openclaw`. -- Зміни, що зберігаються, як і раніше потребують підтвердження, навіть у режимі відновлення. -- Аудитуйте кожну застосовану операцію відновлення, включно з каналом, обліковим записом, відправником, - ключем сеансу, операцією, хешем конфігурації до та хешем конфігурації після. -- Ніколи не віддзеркалюйте секрети. Перевірка SecretRef має повідомляти про доступність, а не про значення. -- Якщо Gateway працює, віддавайте перевагу типізованим операціям Gateway. Якщо Gateway - недоступний, використовуйте лише мінімальну локальну поверхню відновлення, яка не залежить від - звичайного циклу агента. + де середовище виконання вже має локальні повноваження без sandbox. +- Вимагати явної identity власника. Відновлення не повинно приймати правила відправника з wildcard, відкриту політику group, + неавтентифіковані Webhook або анонімні канали. +- Лише owner DM за замовчуванням. Відновлення в group/channel потребує явного opt-in і + все одно має маршрутизувати запити на підтвердження до owner DM. +- Віддалене відновлення не може відкрити локальний TUI або перемкнутися в інтерактивну сесію агента. + Для передачі агенту використовуйте локальний `openclaw`. +- Постійні записи все одно потребують підтвердження, навіть у режимі відновлення. +- Аудитуйте кожну застосовану операцію відновлення, включно з channel, account, sender, + ключем session, операцією, хешем конфігурації до та хешем конфігурації після. +- Ніколи не віддзеркалюйте секрети. Перевірка SecretRef має повідомляти про доступність, а не + про значення. +- Якщо Gateway працює, надавайте перевагу типізованим операціям Gateway. Якщо Gateway + не працює, використовуйте лише мінімальну локальну поверхню відновлення, яка не залежить + від звичайного циклу агента. Форма конфігурації: @@ -272,11 +273,11 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5 `enabled` має приймати: -- `"auto"`: за замовчуванням. Дозволяти лише тоді, коли ефективний runtime — YOLO, а +- `"auto"`: значення за замовчуванням. Дозволяти лише тоді, коли ефективне середовище виконання — YOLO, а sandboxing вимкнено. - `false`: ніколи не дозволяти відновлення через канал повідомлень. - `true`: явно дозволяти відновлення, коли перевірки owner/channel пройдено. Це - все одно не повинно обходити відмову через sandboxing. + все одно не повинно обходити заборону sandboxing. Поведінка YOLO за замовчуванням для `"auto"`: @@ -290,32 +291,37 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5 pnpm test:docker:crestodian-rescue ``` -Резервний локальний planner без конфігурації покривається: +Резервний локальний планувальник у безконфігураційному режимі покривається: ```bash pnpm test:docker:crestodian-planner ``` -Опціональна live smoke-перевірка поверхні команд каналу перевіряє `/crestodian status` плюс -повний цикл підтвердження змін, що зберігаються, через обробник відновлення: +Opt-in live smoke-перевірка поверхні команд каналу перевіряє `/crestodian status`, а також +цикл постійного підтвердження через обробник відновлення: ```bash pnpm test:live:crestodian-rescue-channel ``` -Налаштування без конфігурації з нуля через Crestodian покривається: +Нове безконфігураційне налаштування через Crestodian покривається: ```bash pnpm test:docker:crestodian-first-run ``` -Ця lane починається з порожнього каталогу стану, спрямовує `openclaw` без команди до Crestodian, -встановлює модель за замовчуванням, створює додаткового агента, налаштовує Discord через -SecretRef токена, перевіряє конфігурацію та перевіряє журнал аудиту. +Ця lane починається з порожнього каталогу стану, спрямовує `openclaw` без аргументів до Crestodian, +установлює модель за замовчуванням, створює додаткового агента, налаштовує Discord через +увімкнення Plugin та token SecretRef, виконує validate config і перевіряє журнал +аудиту. QA Lab також має сценарій із підтримкою repo для того самого потоку Ring 0: + +```bash +pnpm openclaw qa suite --scenario crestodian-ring-zero-setup +``` ## Пов’язане -- [Довідник CLI](/uk/cli) +- [Довідка CLI](/uk/cli) - [Doctor](/uk/cli/doctor) - [TUI](/uk/cli/tui) - [Sandbox](/uk/cli/sandbox) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index a2a41ba63..6c2e3477d 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,22 +3,22 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для багів моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker runners і що охоплює кожен тест' +summary: 'Набір для тестування: модульні/e2e/live набори, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-25T11:56:31Z" + generated_at: "2026-04-25T12:18:24Z" model: gpt-5.4 provider: openai - source_hash: b525ad9cc015d8bb5d4ed8894394ee00a42ac7de0ed8695b3da342094d141309 + source_hash: f0db8300a2a1b8367faca0aa1a857d67c06723eb4170e86440f827a802d05a34 source_path: help/testing.md workflow: 15 --- OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker runners. Цей документ — посібник «як ми тестуємо»: +Docker-ранерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем із моделями/провайдерами. @@ -27,186 +27,189 @@ Docker runners. Цей документ — посібник «як ми тес У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` -- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Прямий цикл Vitest watch: `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-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + зондування інструментів/зображень Gateway): `pnpm test:live` -- Цільовий запуск одного live-файлу без зайвого виводу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live sweep моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелике зондування у стилі читання файлу. - Моделі, у метаданих яких заявлено вхід `image`, також виконують невеликий хід із зображенням. - Вимкніть додаткові зондування за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Точково запустити один live-файл у тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker-прогін live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер запускає текстовий хід, а також невелику перевірку у стилі читання файлу. + Моделі, чиї метадані вказують вхід `image`, також запускають невеликий хід із зображенням. + Вимкніть додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, що включає окремі Docker live jobs для матриці моделей, + `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `include_live_suites: true`, який включає окремі матричні job-и Docker live model, розбиті за провайдером. - - Для цільових повторних запусків у CI запустіть `OpenClaw Live And E2E Checks (Reusable)` + - Для точкових повторних запусків у CI вручну запускайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові важливі секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до - `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - викликів за розкладом/для релізів. -- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху app-server Codex, прив’язує синтетичний - Slack DM за допомогою `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення - маршрутизуються через native plugin binding, а не через ACP. -- Smoke-тест команди порятунку Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Додаткова перевірка message-channel rescue command surface, що вмикається за бажанням. - Вона виконує `/crestodian status`, ставить у чергу стійку зміну моделі, - відповідає `/crestodian yes` і перевіряє шлях запису аудиту/конфігурації. -- Docker smoke планувальника Crestodian: `pnpm test:docker:crestodian-planner` + - Додавайте нові високосигнальні секрети провайдерів у `scripts/ci-hydrate-live-auth.sh`, а також у + `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його виклики + зі schedule/release. +- Димовий тест native Codex bound-chat: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний + Slack DM через `/codex bind`, виконує `/codex fast` і + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення із зображенням + проходять через native plugin binding, а не через ACP. +- Димовий тест команди порятунку Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Opt-in belt-and-suspenders перевірка поверхні команди порятунку message-channel. + Вона виконує `/crestodian status`, ставить у чергу зміну persistent model, + відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Docker-димовий тест planner-а Crestodian: `pnpm test:docker:crestodian-planner` - Запускає Crestodian у контейнері без конфігурації з підробленим Claude CLI у `PATH` - і перевіряє, що fallback нечіткого планувальника перетворюється на - типізований запис у конфігурацію з аудитом. -- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, маршрутизує простий `openclaw` до - Crestodian, застосовує записи setup/model/agent/Discord SecretRef, перевіряє - конфігурацію та записи аудиту. -- Smoke вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований + і перевіряє, що резервний fuzzy planner перетворюється на audited typed + config write. +- Docker-димовий тест першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до + Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, + валідує конфігурацію та перевіряє записи аудиту. Той самий шлях налаштування Ring 0 + також покривається в QA Lab через + `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. +- Димовий тест вартості Moonshot/Kimi: якщо задано `MOONSHOT_API_KEY`, запустіть + `openclaw models list --provider moonshot --json`, а потім виконайте ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON містить Moonshot/K2.6, а в - транскрипті помічника збережено нормалізоване `usage.cost`. + проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6 і що + транскрипт асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один проблемний випадок, віддавайте перевагу звуженню live-тестів за допомогою змінних середовища allowlist, описаних нижче. +Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## QA-специфічні runners +## Ранери для QA -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм QA Lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і -через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний запуск із mock parity gate, live Matrix lane і -live Telegram lane під керуванням Convex як паралельними jobs. `OpenClaw Release Checks` -запускає ті самі lanes перед затвердженням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR +і при ручному запуску з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і вручну з mock parity gate, live Matrix lane та +керованим Convex live Telegram lane як паралельними job-ами. `OpenClaw Release Checks` +запускає ті самі lane-и перед погодженням релізу. - `pnpm openclaw qa suite` - - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - Запускає сценарії QA на базі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - workers Gateway. Для `qa-channel` типовою є concurrency 4 (обмежена - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість workers, або `--concurrency 1` для старішого послідовного lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли + працівниками Gateway. Для `qa-channel` за замовчуванням використовується concurrency 4 + (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість працівників, або `--concurrency 1` для старого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і mock-протоколу, не замінюючи lane - `mock-openai`, що враховує сценарії. + покриття фікстур і protocol-mock без заміни lane `mock-openai`, + орієнтованого на сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають до гостьової системи підтримувані вхідні дані автентифікації QA, які практично використовувати: - ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, - якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + - Для live-запусків передає підтримувані вхідні дані автентифікації QA, які практично + використовувати в гостьовій системі: + ключі провайдера через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він заданий. + - Каталоги виводу мають залишатися під коренем репозиторію, щоб гостьова система могла записувати назад через змонтовану робочу область. - - Записує звичайний QA report + summary, а також журнали Multipass у + - Записує звичайний QA-звіт і summary, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточного checkout, встановлює його глобально в - Docker, виконує неінтерактивне налаштування з ключем OpenAI API, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення plugin встановлює runtime dependencies на вимогу, + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний onboarding з ключем OpenAI API, типово налаштовує + Telegram, перевіряє, що ввімкнення plugin встановлює runtime-залежності на вимогу, запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane - встановлення з пакета для Discord. + пакетного встановлення з Discord. - `pnpm test:docker:npm-telegram-live` - - Встановлює опублікований пакет OpenClaw у Docker, виконує налаштування встановленого пакета, - налаштовує Telegram через встановлений CLI, а потім повторно використовує + - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding + для встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує live Telegram QA lane з цим встановленим пакетом як Gateway SUT. - - Типово використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. + - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/релізів установіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо + `pnpm openclaw qa telegram`. Для автоматизації CI/release задайте + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` разом із + `OPENCLAW_QA_CONVEX_SITE_URL` і секретом ролі. Якщо `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker wrapper автоматично вибирає Convex. + Docker-обгортка автоматично вибирає Convex. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - GitHub Actions надає цей lane як ручний workflow для мейнтейнерів - `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує - середовище `qa-live-shared` і оренди облікових даних CI Convex. + `NPM Telegram Beta E2E`. Він не запускається при merge. Workflow використовує + середовище `qa-live-shared` і оренди облікових даних Convex CI. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування конфігурації. - - Перевіряє, що виявлення setup залишає runtime dependencies - не налаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor - встановлює runtime dependencies кожного bundled plugin на вимогу, і що другий restart - не перевстановлює dependencies, які вже були активовані. - - Також встановлює відому старішу npm-базу, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що post-update doctor - кандидата відновлює runtime dependencies bundled channel без - postinstall-відновлення з боку harness. + з налаштованим OpenAI, а потім вмикає bundled channel/plugin через редагування конфігурації. + - Перевіряє, що виявлення setup залишає відсутніми runtime-залежності + plugin, які не налаштовано, що перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного bundled plugin на вимогу, і що другий рестарт не перевстановлює + залежності, які вже були активовані. + - Також установлює відомий старіший npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor після оновлення в кандидата + виправляє bundled channel runtime dependencies без післявстановлювального + виправлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає native smoke оновлення встановленого пакета у гостьових системах Parallels. Кожна - вибрана платформа спочатку встановлює потрібний базовий пакет, потім виконує - встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє встановлену + - Запускає native packaged-install димовий тест оновлення через гостьові системи Parallels. Кожна + вибрана платформа спочатку встановлює потрібний baseline package, а потім запускає + встановлену команду `openclaw update` у тій самій гостьовій системі та перевіряє встановлену версію, статус оновлення, готовність gateway і один локальний хід агента. - - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, коли ітеруєтеся - над однією гостьовою системою. Використовуйте `--json` для шляху до підсумкового артефакту та + - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, коли + ітеруєте лише одну гостьову систему. Використовуйте `--json` для шляху до summary artifact і статусу кожного lane. - - Обгортайте довгі локальні запуски тайм-аутом на хості, щоб зависання транспорту Parallels не - забирало решту часу на тестування: + - Обгортайте тривалі локальні запуски тайм-аутом хоста, щоб збої транспорту Parallels + не з’їли решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені журнали lanes у `/tmp/openclaw-parallels-npm-update.*`. + - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, - перш ніж вважати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/відновлення runtime - dependencies на холодній гостьовій системі; це все ще є нормою, якщо вкладений - журнал налагодження npm продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke lanes Parallels - для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час - відновлення snapshot, роздачі пакета або стану gateway у гостьовій системі. - - Post-update proof запускає звичайну поверхню bundled plugin, оскільки - фасади можливостей, як-от мовлення, генерація зображень і - розуміння медіа, завантажуються через bundled runtime APIs, навіть якщо сам + перш ніж припускати, що зовнішня обгортка зависла. + - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/runtime + repair dependencies у холодній гостьовій системі; це все ще нормально, якщо вкладений + npm debug log продовжує оновлюватися. + - Не запускайте цю агреговану обгортку паралельно з окремими димовими lane-ами Parallels + для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати через + відновлення snapshot, роздачу пакетів або стан guest gateway. + - Доказ після оновлення запускає звичайну поверхню bundled plugin, оскільки + capability facades, як-от speech, image generation і media + understanding, завантажуються через bundled runtime API навіть тоді, коли сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування - протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого димового + тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає Matrix live QA lane проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Встановлені з пакета OpenClaw не постачають - `qa-lab`, тому не надають `openclaw qa`. - - Checkout репозиторію завантажують bundled runner напряму; окремий крок встановлення plugin не потрібен. + - Запускає Matrix live QA lane проти тимчасового Tuwunel homeserver на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні встановлення OpenClaw не постачають + `qa-lab`, тому вони не надають `openclaw qa`. + - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок + встановлення plugin не потрібен. - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix plugin як транспортом SUT. - - Типово використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. - - Записує Matrix QA report, summary, observed-events artifact і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. - - Типово виводить прогрес і застосовує жорсткий тайм-аут запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а в разі збоїв додається команда відновлення `docker compose ... down --remove-orphans`. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane створює тимчасових користувачів локально. + - Записує Matrix QA report, summary, observed-events artifact і об’єднаний журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить прогрес і примусово застосовує жорсткий тайм-аут виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а у випадку збоїв додається команда відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - Запускає Telegram live QA lane проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулів облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути спільні оренди. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли вам - потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження ботів один за одним увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на відправлення driver до спостережуваної відповіді SUT. + - Підтримує `--credential-source convex` для спільних пулів облікових даних. За замовчуванням використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live transport lanes використовують один стандартний контракт, щоб нові транспорти не розходилися: +Live transport lane-и мають один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. | Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | | -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | @@ -216,24 +219,24 @@ Live transport lanes використовують один стандартни ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -для цієї оренди під час роботи lane і звільняє оренду під час завершення. +QA lab отримує ексклюзивну lease з пулу на базі Convex, надсилає heartbeat +цієї lease, поки lane працює, і звільняє lease під час завершення роботи. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI типово `ci`, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -241,7 +244,7 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-и Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. @@ -257,11 +260,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Перед live-запусками використовуйте `doctor`, щоб перевірити URL сайту Convex, секрети брокера, -префікс endpoint, HTTP-тайм-аут і доступність admin/list без виведення -значень секретів. Використовуйте `--json` для машиночитного виводу в скриптах і CI-утилітах. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайта Convex, секрети broker, +endpoint prefix, HTTP timeout і доступність admin/list без виведення +значень секретів. Використовуйте `--json` для machine-readable виводу у скриптах і CI +утилітах. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -279,7 +283,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -288,59 +292,59 @@ pnpm openclaw qa credentials remove --credential-id - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` має бути рядком із числовим Telegram chat id. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. +- `admin/add` валідує цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання каналу до QA -Додавання каналу до системи markdown QA потребує рівно двох речей: +Додавання каналу до markdown QA system вимагає рівно двох речей: 1. Транспортного адаптера для каналу. -2. Пакета сценаріїв, що перевіряє контракт каналу. +2. Набору сценаріїв, що перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим процесом. +Не додавайте новий кореневий QA-командний root верхнього рівня, якщо спільний хост `qa-lab` може +взяти цей потік на себе. `qa-lab` відповідає за спільну механіку хоста: -- кореневу команду `openclaw qa` -- запуск і завершення набору -- concurrency workers +- root команди `openclaw qa` +- запуск і завершення suite +- concurrency працівників - запис артефактів -- генерацію report +- генерацію звітів - виконання сценаріїв - compatibility aliases для старіших сценаріїв `qa-channel` -Runner plugins відповідають за транспортний контракт: +Runner plugin-и відповідають за транспортний контракт: -- як `openclaw qa ` монтується під спільним коренем `qa` +- як `openclaw qa ` монтується під спільним root `qa` - як gateway налаштовується для цього транспорту - як перевіряється готовність -- як інжектяться вхідні події +- як ін’єктуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти й нормалізований стан транспорту +- як надаються транскрипти та нормалізований стан транспорту - як виконуються дії на базі транспорту -- як виконується специфічний для транспорту reset або cleanup +- як обробляється transport-specific reset або cleanup Мінімальний поріг прийняття для нового каналу: -1. Залишайте `qa-lab` власником спільного кореня `qa`. +1. Залишайте `qa-lab` власником спільного root `qa`. 2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Залишайте специфічну для транспорту механіку всередині runner plugin або harness каналу. -4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Залишайте `runtime-api.ts` легким; ледаче виконання CLI і runner має залишатися за окремими entrypoints. +3. Залишайте transport-specific механіку всередині runner plugin або harness каналу. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої root-команди. + Runner plugin-и мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; lazy CLI і виконання runner мають залишатися за окремими entrypoint-ами. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic helpers для нових сценаріїв. -7. Зберігайте роботу наявних compatibility aliases, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте generic scenario helpers для нових сценаріїв. +7. Зберігайте працездатність наявних compatibility aliases, якщо тільки репозиторій не виконує навмисну міграцію. -Правило ухвалення рішення суворе: +Правило прийняття рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту каналу, залишайте її в цьому runner plugin або harness plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість специфічної для каналу гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно відображайте це в контракті сценарію. +- Якщо поведінка залежить від одного channel transport, залишайте її в цьому runner plugin або harness plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. -Для нових сценаріїв бажані такі назви generic helpers: +Бажані назви generic helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -363,55 +367,55 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати назви generic helpers. -Compatibility aliases існують, щоб уникнути міграції в один день, а не як модель для +Нова робота над каналами має використовувати generic helper names. +Compatibility aliases існують, щоб уникнути міграції типу flag day, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання flaky/cost): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: нецільові запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати shards із кількома проєктами в конфігурації окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що охоплюються `vitest.unit.config.ts` +- Конфігурація: неточкові запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в per-project configs для паралельного планування +- Файли: inventories core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, які покриває `vitest.unit.config.ts` - Обсяг: - - Чисті unit-тести - - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресійні тести для відомих багів + - Чисті модульні тести + - In-process інтеграційні тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресії для відомих багів - Очікування: - - Запускаються в CI - - Не потребують реальних ключів - - Мають бути швидкими й стабільними + - Запускається в CI + - Не потребує реальних ключів + - Має бути швидким і стабільним - + - - Нецільовий `pnpm test` запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу root-project. Це зменшує пік RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` як і раніше використовує нативний граф проєктів root `vitest.config.ts`, оскільки цикл спостереження з кількома shards є непрактичним. - - `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 торкається лише маршрутованих source/test-файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один прохід перевірки extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем version верхнього рівня. - - Unit-тести з легкими імпортами з agents, commands, plugins, хелперів auto-reply, `plugin-sdk` і подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lanes. - - Вибрані helper source-файли `plugin-sdk` і `commands` також відображають changed-mode запуски на явні sibling-тести в цих легких lanes, тому зміни хелперів не запускають повторно весь важкий набір для цього каталогу. - - `auto-reply` має три окремі buckets: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness відповідей поза дешевими тестами status/chunk/token. + - Неточкові запуски `pnpm test` використовують дванадцять менших shard-конфігів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл watch із багатьма shard-ами є непрактичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lane-и, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lane-и, коли diff зачіпає лише маршрутизовні файли source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root project. + - `pnpm check:changed` — це звичайний smart local gate для вузьких змін. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lane-и typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один validation pass для extension, оскільки extensions залежать від цих контрактів core. Зміни версій лише в release metadata запускають точкові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни пакета поза полем версії верхнього рівня. + - Unit-тести з легкими імпортами з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних суто утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lane-ах. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють запуски в changed mode з явними sibling test-ами в цих легких lane-ах, тож редагування helper-ів не змушують повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` має три окремі bucket-и: helper-и core верхнього рівня, інтеграційні тести `reply.*` верхнього рівня та піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness-а reply потрапляти в дешеві тести status/chunk/token. - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст - Compaction, зберігайте обидва рівні покриття. - - Додавайте цільові регресійні helper-тести для чистих меж - маршрутизації та нормалізації. - - Підтримуйте healthy стан integration-наборів embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + зберігайте обидва рівні покриття. + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та + нормалізації. + - Підтримуйте в доброму стані інтеграційні набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction як і раніше проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є - достатньою заміною цих integration-шляхів. + - Ці набори перевіряють, що scoped id і поведінка Compaction все ще проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише для helper-ів + не є достатньою заміною цих інтеграційних шляхів. @@ -419,373 +423,373 @@ Compatibility aliases існують, щоб уникнути міграції - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у root projects, e2e і live configs. - - Root UI lane зберігає свій `jsdom` setup та optimizer, але також запускається на - спільному неізольованому runner. + non-isolated runner у root projects, e2e і live configs. + - Root lane UI зберігає свої `jsdom` setup і optimizer, але теж працює на + спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + Задайте `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - + - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли в stage і + - `pnpm changed:lanes` показує, які архітектурні lane-и запускає diff. + - Хук pre-commit виконує лише форматування. Він повторно індексує відформатовані файли і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли - вам потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract - включають один прохід перевірки extension. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чітко відображаються на менший набір. + - Явно запускайте `pnpm check:changed` перед передачею або push, коли вам + потрібен smart local gate. Зміни публічного Plugin SDK і plugin-contract + включають один validation pass для extension. + - `pnpm test:changed` маршрутизує через scoped lane-и, коли змінені шляхи + чисто зіставляються з меншим набором. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом workers. - - Автомасштабування локальних workers навмисно консервативне і зменшує навантаження, - коли середнє навантаження хоста вже високе, тому кілька одночасних + лише з вищим лімітом працівників. + - Автомасштабування локальних працівників навмисно консервативне й зменшує навантаження, + коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли - змінюється wiring тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на - підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо - хочете одне явне розташування кешу для прямого профілювання. + - Базова конфігурація Vitest позначає проєкти/конфіг-файли як + `forceRerunTriggers`, щоб повторні запуски в changed mode залишалися коректними, + коли змінюється wiring тестів. + - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; задайте `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс - вивід деталізації імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд - файлами, зміненими від `origin/main`. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту, а також + вивід розбивки імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд + файлами, зміненими відносно `origin/main`. - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, - тримайте важкі dependencies за вузьким локальним seam `*.runtime.ts` і - напряму мокайте цей seam замість deep-import runtime-хелперів - лише для того, щоб передати їх у `vi.mock(...)`. + тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і + напряму мокайте цей seam замість глибоких імпортів runtime helper-ів лише для того, + щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із нативним шляхом root-project для цього зафіксованого - diff і виводить wall time плюс macOS max RSS. + `test:changed` з native root-project path для цього закоміченого diff і виводить + wall time плюс macOS max RSS. - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для - накладних витрат запуску й трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для + `scripts/test-projects.mjs` і root-конфіг Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main thread для + накладних витрат запуску і transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner-а для unit-набору з вимкненим паралелізмом файлів. -### Стабільність (gateway) +### Stability (Gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker +- Конфігурація: `vitest.gateway.config.ts`, примусово один працівник - Обсяг: - - Запускає реальний loopback Gateway з діагностикою, увімкненою типово - - Пропускає синтетичне churn повідомлень gateway, пам’яті й великих payload через шлях діагностичних подій - - Виконує запити до `diagnostics.stability` через WS RPC Gateway - - Охоплює хелпери збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету тиску, а глибина черг на рівні сесії повертається до нуля + - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням + - Пропускає синтетичну churn-активність повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через Gateway WS RPC + - Покриває helper-и збереження diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS залишаються в межах budget тиску, а глибини черг на рівні сесій знову спадають до нуля - Очікування: - Безпечно для CI і без ключів - - Вузький lane для подальшого опрацювання регресій стабільності, а не заміна повного набору Gateway + - Вузький lane для подальшої перевірки регресій стабільності, а не заміна повного набору Gateway -### E2E (gateway smoke) +### E2E (димовий тест Gateway) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести під `extensions/` -- Типові параметри runtime: +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled plugin під `extensions/` +- Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: 1 типово). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на вивід у консоль. + - Використовує адаптивну кількість працівників (CI: до 2, локально: типово 1). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати консолі I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість працівників (максимум 16). - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairинг Node і важча мережева взаємодія + - End-to-end поведінка Gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, спарювання Node і важчий мережевий стек - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (можуть бути повільнішими) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke backend OpenShell +### E2E: димовий тест бекенду OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи remote-canonical через sandbox fs bridge + - Запускає ізольований OpenShell Gateway на хості через Docker + - Створює sandbox з тимчасового локального Dockerfile + - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через fs bridge sandbox - Очікування: - - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і справного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише за opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і працездатного Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI binary або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести під `extensions/` -- Типово: **увімкнено** командою `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled plugin під `extensions/` +- Типово: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - «Чи справді цей провайдер/модель _сьогодні_ працює з реальними обліковими даними?» - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштують грошей / використовують rate limits + - За задумом нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, outages) + - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. -- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. -- Вивід прогресу/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-запуски підтягують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Задавайте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але пригнічує додаткове повідомлення `~/.profile` і заглушує bootstrap-журнали gateway/шум Bonjour. Задайте `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову побачити повні стартові журнали. +- Ротація API-ключів (залежно від провайдера): задавайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. +- Вивід прогресу/heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні навіть тоді, коли перехоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. + - Налаштовуйте heartbeat прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтесь мережевої взаємодії gateway / WS-протоколу / pairинг: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / tool calling: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої взаємодії Gateway / протоколу WS / спарювання: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` -## Live-тести (що взаємодіють із мережею) +## Live-тести (із мережевими зверненнями) -Для live-матриці моделей, smoke backend CLI, smoke ACP, harness app-server Codex -і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також обробки облікових даних для live-запусків — див. +Для матриці live-моделей, димових тестів бекенду CLI, димових тестів ACP, harness-а +Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також для обробки облікових даних під час live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). -## Docker runners (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві категорії: +Ці Docker-ранери поділяються на дві категорії: -- Docker runners для live-моделей: `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 і робочу область (і читають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners типово мають меншу межу smoke, щоб повний Docker sweep залишався практичним: +- Docker-ранери live-моделей: `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 і робочу область (і підтягують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runner-и типово використовують менший smoke cap, щоб повний Docker-прогін залишався практичним: `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-змінні, коли - свідомо хочете більший вичерпний прогін. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для live Docker lanes. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke runners E2E, які перевіряють зібраний застосунок. Агрегатор використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а resource caps не дають важким live-, npm-install- і multi-service-lanes запускатися одночасно. Типові значення — 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише коли Docker-хост має більше запасу ресурсів. Runner типово виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає таймінги успішних lanes у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках починати з довших lanes. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lanes без збирання або запуску Docker. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + навмисно хочете більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для Docker live lane-ів. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E container smoke runner-ів, які перевіряють зібраний застосунок. Агрегат використовує ваговий локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дозволяють одночасно стартувати всім важким live, npm-install і multi-service lane-ам. Типові значення — 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більший запас ресурсів. Runner типово виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, виводить статус кожні 30 секунд, зберігає таймінги успішних lane-ів у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спочатку стартували довші lane-и. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести ваговий маніфест lane-ів без збирання або запуску Docker. +- Container smoke runner-и: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` підіймають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker runners для live-моделей також bind-mount лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth store хоста: +Docker-ранери live-моделей також bind-mount-ять лише потрібні CLI auth home-и (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth store хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- CLI backend smoke: `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: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Димовий тест CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Димовий тест harness-а Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke онбордингу/каналу/агента для npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і Telegram за замовчуванням, перевіряє, що doctor відновлює runtime deps активованого plugin, і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збирання на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache між контейнерами root, update і direct-npm. Smoke оновлення типово використовує npm `latest` як стабільну базу перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. -- Install Smoke у CI пропускає дубльоване пряме глобальне оновлення npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- CLI smoke видалення спільної робочої області агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає образ root Dockerfile, створює два агенти з однією робочою областю в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON та поведінку збереження робочої області. Повторно використовуйте образ install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Регресія мінімального reasoning для OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово викликає відхилення схеми провайдера і перевіряє, що raw detail з’являється в журналах Gateway. -- Міст MCP channel (seeded Gateway + stdio bridge + raw smoke кадру сповіщення Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP пакета Pi (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків Cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + alias `/plugin` + семантика restart пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжого локального збирання через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегатор один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні lanes, включно з окремими lanes оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. -- Звужуйте runtime deps bundled plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Димовий тест npm tarball onboarding/channel/agent: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref плюс типово Telegram, перевіряє, що doctor відновлює runtime deps активованого plugin, і запускає один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Димовий тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, установлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує один спільний npm cache для своїх root-, update- і direct-npm-контейнерів. Update smoke типово використовує npm `latest` як стабільний baseline перед оновленням до tarball кандидата. Перевірки installer-а без root зберігають ізольований npm cache, щоб записи cache, створені root, не маскували поведінку локального встановлення користувача. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm у локальних повторних запусках. +- Install Smoke у CI пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- CLI smoke для видалення спільної робочої області агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає образ root Dockerfile, створює два агенти з однією робочою областю в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON, а також поведінку збереженої робочої області. Повторно використовуйте образ install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово викликає відхилення provider schema і перевіряє, що сирий detail з’являється в журналах Gateway. +- Міст MCP channel (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP server + smoke allow/deny для embedded Pi profile): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugin-и (install smoke + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Димовий тест незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Димовий тест метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker-образ runner-а, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожний сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте host rebuild після свіжого локального build через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вказуйте на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні lane-и, включно з окремими lane-ами оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю channel під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Під час ітерацій звужуйте runtime deps bundled plugin, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використати спільний образ built-app: +Щоб вручну попередньо зібрати й повторно використовувати спільний образ built-app: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, як і раніше мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти виконують його pull, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfiles, оскільки вони перевіряють поведінку пакета/встановлення, а не спільний runtime зібраного застосунку. +Перевизначення образів для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо він ще не локальний. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. -Docker runners для live-моделей також bind-mount поточний checkout лише для читання і -розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним, водночас дозволяючи запускати Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні кеші та результати збирання застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -Gradle output, щоб Docker live-запуски не витрачали хвилини на копіювання +Docker-ранери live-моделей також bind-mount-ять поточний checkout у режимі лише для читання і +розміщують його в тимчасовому робочому каталозі всередині контейнера. Це зберігає runtime +образ компактним, водночас усе ще запускаючи Vitest проти ваших точних локальних source/config. +Крок staging пропускає великі локальні кеші та результати збірки застосунку, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. +Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали +реальні працівники каналів Telegram/Discord/etc. усередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway live-покриття з цього Docker lane. -`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, -запускає pinned контейнер Open WebUI проти цього gateway, входить через +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер gateway OpenClaw з увімкненими HTTP endpoint OpenAI-compatible, +запускає зафіксований контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через проксі Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути -образ Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. -Цей lane очікує придатний live-ключ моделі, і `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat-запит через проксі Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити +образ Open WebUI, а Open WebUI може знадобитися завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Docker-ized запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -container, запускає другий контейнер, що стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих conversation, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію outbound send, а також channel + сповіщення про дозволи -у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -напряму перевіряє raw stdio MCP frames, тож smoke-тест перевіряє те, що міст -справді надсилає, а не лише те, що випадково показує конкретний client SDK. +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає підготовлений Gateway +контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання і channel + +permission-сповіщення у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що міст +справді надсилає, а не лише те, що випадково показує конкретний клієнтський SDK. `test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -live-ключа моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей сервер через embedded runtime пакета Pi -MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через embedded Pi bundle +MCP runtime, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live-ключа моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає підготовлений Gateway з реальним stdio MCP probe server, виконує ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, -що дочірній MCP-процес завершується після кожного запуску. +що дочірній процес MCP завершується після кожного запуску. -Ручний smoke-тест ACP plain-language thread (не для CI): +Ручний ACP plain-language thread smoke (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, прочитані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх mount для CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підтягується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підхоплені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI-auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли CLI auth під `$HOME` монтуються в режимі лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Для звужених запусків провайдера монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, як-от `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібне нове збирання -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища profile (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібне перевзбирання +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища profile (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke-тесту Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke-тест Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег образу Open WebUI -## Перевірка документації +## Перевірка docs -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Після редагування docs запускайте перевірки docs: `pnpm check:docs`. Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний loop gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard Gateway (WS `wizard.start`/`wizard.next`, записує config + примусово вимагає auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `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") -## Evals надійності агента (Skills) +## Оцінювання надійності агентів (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Mock tool-calling через реальний loop gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють wiring сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): -- **Decisioning:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? -- **Workflow contracts:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає неактуальних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні evals мають насамперед залишатися детермінованими: +Майбутні eval-и спочатку мають залишатися детермінованими: -- Runner сценаріїв на базі mock-провайдерів для перевірки викликів інструментів + їх порядку, читання skill-файлів і wiring сесій. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-evals (лише за явним увімкненням, із gating через env) — лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval-и (opt-in, із gate через env) лише після того, як з’явиться безпечний для CI набір. -## Contract-тести (форма Plugin і channel) +## Контрактні тести (форма plugin і channel) -Contract-тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -контракту інтерфейсу. Вони проходять по всіх знайдених plugins і запускають набір +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму контракту інтерфейсу. Вони проходять по всіх виявлених plugin-ах і запускають набір перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, -коли торкаєтеся спільних поверхонь channel або провайдера. +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди -- Усі contracts: `pnpm test:contracts` -- Лише contracts каналів: `pnpm test:contracts:channels` -- Лише contracts провайдерів: `pnpm test:contracts:plugins` +- Усі контракти: `pnpm test:contracts` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Contract-тести каналів +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт wizard налаштування +- **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка ID thread -- **directory** - API каталогу/реєстру -- **group-policy** - Примусове застосування групової політики +- **actions** - Обробники дій channel +- **threading** - Обробка thread ID +- **directory** - API каталогу/складу +- **group-policy** - Примусове застосування політики групи -### Контракти статусу провайдерів +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Зондування статусу каналу -- **registry** - Форма реєстру Plugin +- **status** - Перевірки статусу channel +- **registry** - Форма registry plugin -### Contract-тести провайдерів +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/selection автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/підбір auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin - **runtime** - Runtime провайдера -- **shape** - Форма/інтерфейс Plugin -- **wizard** - Wizard налаштування +- **shape** - Форма/інтерфейс plugin +- **wizard** - Майстер налаштування ### Коли запускати -- Після зміни exports або subpaths у plugin-sdk +- Після зміни export-ів або subpath-ів plugin-sdk - Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації Plugin або виявлення +- Після рефакторингу реєстрації або виявлення plugin -Contract-тести запускаються в CI й не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресійних тестів (рекомендації) +## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо вона за своєю природою лише для live (rate limits, політики auth), залишайте live-тест вузьким і таким, що вмикається через env-змінні -- Віддавайте перевагу націлюванню на найменший шар, який ловить баг: - - баг конвертації/відтворення запиту провайдера → тест прямих моделей - - баг у pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на кожен клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id із сегментами обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) +- Якщо вона за своєю природою лише live (rate limits, політики auth), зберігайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу націлюванню на найменший шар, який виявляє баг: + - баг конвертації/відтворення запиту провайдера → тест direct models + - баг сесії/history/tool pipeline gateway → gateway live smoke або безпечний для CI gateway mock test +- Guardrail обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. -## Пов’язане +## Пов’язані матеріали -- [Тестування live](/uk/help/testing-live) +- [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci)