diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index e985ca072..c3065de8e 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/провайдерів - - Налагодження поведінки gateway + agent -summary: 'Набір для тестування: модульні/e2e/live набори, виконавці Docker і що охоплює кожен тест' + - Додавання регресійних тестів для багів моделей/провайдерів + - Налагодження поведінки gateway та агента +summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-10T20:28:58Z" + generated_at: "2026-04-10T22:08:56Z" model: gpt-5.4 provider: openai - source_hash: e19cfbfcc708c0075d77364e2f20d8e8b8c4300cba97b0c525524882612b7cad + source_hash: e7e00673ca5f54f05d016922432ae4394c3b4eefd867cc23b7a7a57b2c330c39 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір виконавців Docker. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих сценаріїв (локально, перед push, налагодження) +- Які команди запускати для поширених сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -32,277 +32,272 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерації над однією помилкою спершу віддавайте перевагу цільовим запускам. +- Пряма адресація файлу тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над одним збоєм спочатку віддавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-смуга на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA-канал на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Точково запустити один live-файл у тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + gateway-проби інструментів/зображень): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний кейс, краще звузити live-тести через змінні середовища allowlist, описані нижче. -## Спеціальні виконавці QA +## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими працівниками gateway, до 64 працівників або кількості вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування кількості працівників або `--concurrency 1` для старішої послідовної смуги. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway-воркерами, до 64 воркерів або кількості вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування кількості воркерів або `--concurrency 1` для старого послідовного режиму. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Multipass Linux VM. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, практичні для гостьової системи: - ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. + - Live-запуски пересилають підтримувані вхідні дані QA-автентифікації, які практичні для гостьової системи: ключі провайдерів із env, шлях до конфігурації QA live-провайдера та `CODEX_HOME`, якщо він наявний. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує стандартний QA-звіт і підсумок, а також журнали Multipass у - `.artifacts/qa-e2e/...`. + - Записує звичайний QA-звіт і підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на базі Docker для операторської QA-роботи. ## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): -### Unit / integration (типово) +### Unit / integration (типовий режим) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) через наявні scoped Vitest-проєкти - Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - - Чисті модульні тести - - Внутрішньопроцесні інтеграційні тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресії для відомих помилок + - Чисті unit-тести + - In-process integration-тести (gateway auth, routing, tooling, parsing, config) + - Детерміновані регресійні тести для відомих багів - Очікування: - - Запускаються в CI + - Запускається в CI - Реальні ключі не потрібні - - Мають бути швидкими й стабільними -- Примітка про projects: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension виснажувати нерелевантні набори. - - `pnpm test --watch` і далі використовує native root `vitest.config.ts` project graph, тому що цикл watch із багатьма shard-проєктами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; зміни config/setup і далі повертаються до широкого повторного запуску root-project. - - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, тож редагування helper-файлів не вимагає повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration tests і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness впливати на дешеві тести status/chunk/token. -- Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime compaction, - зберігайте обидва рівні покриття. - - Додавайте фокусні helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте в здоровому стані інтеграційні набори embedded runner: + - Має бути швидким і стабільним +- Примітка щодо проєктів: + - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` як і раніше використовує граф проєктів native root `vitest.config.ts`, оскільки цикл watch із багатьма shard не є практичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped-канали, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не сплачує ціну повного старту root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-канали, коли diff торкається лише маршрутизованих source/test-файлів; зміни config/setup як і раніше призводять до fallback на широкий повторний запуск root-project. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі канали, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних каналах. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких каналах, тому зміни helper не змушують повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі кошики: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness потрапляти до дешевих тестів status/chunk/token. +- Примітка щодо embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. + - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. + - Також підтримуйте в хорошому стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction і далі проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих інтеграційних шляхів. -- Примітка про pool: - - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований runner у root projects, e2e і live configs. - - Коренева смуга UI зберігає своє налаштування `jsdom` і optimizer, але тепер також працює на спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидкі локальні ітерації: - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею працівників. - - Автомасштабування локальних працівників тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете явне розташування кешу для прямого профілювання. -- Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту та вивід розбивки імпортів. - - `pnpm test:perf:imports:changed` звужує той самий профільований перегляд до файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU profile основного потоку для накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner-а для unit-набору з вимкненим паралелізмом файлів. + - Ці набори перевіряють, що scoped id і поведінка compaction усе ще проходять через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є достатньою заміною для цих integration-шляхів. +- Примітка щодо pool: + - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований runner у root projects, e2e та live configs. + - Root UI lane зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі значення `threads` + `isolate: false` зі спільної конфігурації Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка щодо швидких локальних ітерацій: + - `pnpm test:changed` маршрутизує через scoped-канали, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативніше й також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфігурація зберігає ввімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка щодо perf-debug: + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпортів і вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий профільований перегляд файлами, зміненими відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project шляхом для цього закоміченого diff і виводить wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для накладних витрат запуску Vitest/Vite і transform. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap для unit-набору з вимкненим паралелізмом файлів. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові налаштування runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість працівників (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. +- Типові параметри runtime: + - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість працівників (обмежено 16). + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing вузлів і більш важкі мережеві сценарії + - End-to-end поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: backend smoke OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований gateway OpenShell на хості через Docker + - Запускає ізольований OpenShell gateway на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання SSH - - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox-а + - Перевіряє OpenClaw OpenShell backend через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише за запитом; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і працездатний демон Docker + - Лише 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 binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper-script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Типовий режим: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки за rate limit + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей tool calling, проблем з auth і поведінки rate limit - Очікування: - - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits + - За задумом не є CI-стабільним (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує ліміти rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски підвантажують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixtures не могли змінювати ваш реальний `~/.openclaw`. +- 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` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він залишає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація 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`. + - 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`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) - Торкаєтесь мережевої частини gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні збої провайдера / виклик інструментів: запускайте звужений `pnpm test:live` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, що наразі оголошується** підключеним Android node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing для застосунку). - - Перевірка gateway `node.invoke` команда за командою для вибраного Android node. -- Необхідне попереднє налаштування: - - Android-застосунок уже підключено й прив’язано до gateway. - - Застосунок має залишатися на передньому плані. - - Для можливостей, які ви очікуєте успішно пройти, мають бути надані дозволи/згода на захоплення. + - Попередньо підготовлений/ручний setup (набір не встановлює, не запускає й не pair-ить застосунок). + - Покомандна перевірка gateway `node.invoke` для вибраного Android node. +- Обов’язковий попередній setup: + - Android-застосунок уже підключений і paired з gateway. + - Застосунок утримується на передньому плані. + - Дозволи/згода на захоплення надані для тих можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі setup Android: [Android App](/uk/platforms/android) -## Live: перевірка моделей (profile keys) +## Live: smoke моделей (ключі профілю) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділені на два рівні, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, що провайдер/модель взагалі можуть відповісти з указаним ключем. +- «Gateway smoke» показує, що повний pipeline gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Шар 1: пряме завершення моделі (без gateway) +### Рівень 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - Виконати невелике completion для кожної моделі (і цільові регресії, де це потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Сучасні/all-прогони за замовчуванням використовують відібрану межу високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншої межі. + - Розгортки modern/all за замовчуванням мають curated high-signal ліміт; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: profile store і резервні варіанти env + - За замовчуванням: profile store і fallback-и env - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки виклику інструментів) + - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: gateway + smoke dev agent-а (те, що насправді робить "@openclaw") +### Рівень 2: smoke gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/змінити сесію `agent:dev:*` (перевизначення моделі на запуск) - - Ітеруватися по моделях із ключами й перевіряти: + - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Ітерувати моделі-із-ключами й перевіряти: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (read probe) + - що працює реальний виклик інструмента (read probe) - необов’язкові додаткові перевірки інструментів (exec+read probe) - - що шляхи регресій OpenAI (лише tool-call → подальший крок) і далі працюють -- Деталі probe-ів (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить agent-а `read` його та повернути nonce назад. - - `exec+read` probe: тест просить agent-а записати nonce у тимчасовий файл через `exec`, а потім зчитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. + - що регресійні шляхи OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - `exec+read` probe: тест просить агента `exec`-записати nonce у тимчасовий файл, а потім `read`-зчитати його назад. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Сучасні/all gateway-прогони за замовчуванням використовують відібрану межу високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншої межі. -- Як вибирати провайдерів (уникаючи «усе з OpenRouter»): + - Розгортки modern/all для gateway за замовчуванням мають curated high-signal ліміт; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникати «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Tool + image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на інструменти) - - image probe запускається, коли модель рекламує підтримку введення зображень - - Потік (високорівнево): - - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Перевірки інструментів і зображень у цьому live-тесті завжди увімкнені: + - `read` probe + `exec+read` probe (стрес-тест інструментів) + - image probe запускається, коли модель оголошує підтримку вхідних зображень + - Потік (на високому рівні): + - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Embedded agent пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) + - Перевірка: відповідь містить `cat` + код (допускається OCR-похибка: незначні помилки дозволені) -Порада: щоб побачити, що можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke backend-а CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent із локальним backend-ом CLI, не торкаючись вашої типової конфігурації. -- Типові значення smoke для конкретного backend-а знаходяться у визначенні `cli-backend.ts` розширення-власника. +- Мета: перевірити pipeline Gateway + agent із використанням локального CLI backend, не торкаючись вашого типового config. +- Типові значення smoke для конкретного backend зберігаються у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin-а backend-а CLI-власника. -- Перевизначення (необов’язкові): + - Поведінка command/args/image береться з метаданих plugin-а відповідного CLI backend. +- Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображення, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи вставляються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість вставлення в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням аргументів зображень, коли задано `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль переключення). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -318,7 +313,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -329,28 +324,28 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Виконавець Docker розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke backend-а CLI всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke CLI з розширення-власника, а потім установлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` від `claude setup-token`. Спершу він доводить, що прямий `claude -p` у Docker працює, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Ця смуга підписки типово вимикає probe-и інструмента/image Claude MCP, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг додаткового використання, а не через звичайні ліміти тарифного плану підписки. -- Live smoke backend-а CLI тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані CLI smoke від відповідного extension, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних Anthropic API-key. Цей subscription-канал за замовчуванням вимикає перевірки Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг додаткового використання замість звичайних лімітів subscription-плану. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke для Claude також патчить сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP із live ACP agent-ом: +- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайне подальше повідомлення в тій самій розмові - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP + - прив’язати synthetic conversation message-channel на місці + - надіслати звичайний follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agent-и в Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст розмови в стилі Slack DM + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` + - Synthetic channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -359,8 +354,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця смуга використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли приєднати контекст message-channel, не вдаючи зовнішню доставку. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent-ів plugin-а `acpx` для вибраного ACP harness agent-а. + - Цей канал використовує surface `chat.send` gateway з admin-only synthetic originating-route fields, щоб тести могли прикріплювати контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований registry агентів plugin-а `acpx` для вибраного ACP harness agent. Приклад: @@ -376,7 +371,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent-а: +Docker-рецепти для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -384,31 +379,33 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Примітки про Docker: +Примітки щодо Docker: -- Виконавець Docker розташовано в `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke ACP bind для всіх підтримуваних live CLI agent-ів послідовно: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, підготовлює відповідний auth-матеріал CLI у контейнер, установлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо він відсутній. -- Усередині Docker виконавець установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, підготовлює відповідні матеріали CLI auth у контейнері, установлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із sourced profile доступними для дочірнього harness CLI. -## Live: smoke harness app-server Codex +## Live: smoke Codex app-server harness -- Мета: перевірити harness Codex, що належить plugin-у, через звичайний метод gateway +- Мета: перевірити Codex harness, що належить plugin-у, через звичайний gateway-метод `agent`: - - завантажити вбудований plugin `codex` + - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік - app-server може відновитися + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що app-server + thread може відновитися + - запустити `/codex status` і `/codex models` через той самий command-path + gateway - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти, тихо переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані + harness не міг пройти тест, тихо переключившись на PI. +- Auth: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -422,20 +419,20 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash source ~/.profile pnpm test:docker:live-codex-harness ``` -Примітки про Docker: +Примітки щодо Docker: -- Виконавець Docker розташовано в `scripts/test-live-codex-harness-docker.sh`. -- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони присутні, установлює `@openai/codex` у записуваний змонтований npm +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth Codex CLI, якщо вони наявні, установлює `@openai/codex` у записуваний змонтований npm префікс, підготовлює вихідне дерево, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням вмикає image і MCP/tool probe-и. Установіть +- Docker за замовчуванням вмикає image і MCP/tool probes. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. @@ -443,35 +440,35 @@ pnpm test:docker:live-codex-harness Вузькі, явні allowlist-и — найшвидші та найменш нестабільні: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів через кількох провайдерів: +- Tool calling для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (Gemini API key + Antigravity): +- Фокус на Google (API key Gemini + Antigravity): - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: - `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint agent-а в стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст Antigravity OAuth (agent endpoint у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний binary `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжності версій). + - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (API key / profile auth); це те, що більшість користувачів мають на увазі під “Gemini”. + - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «списку моделей CI» (live вмикається за запитом), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Фіксованого «списку моделей CI» не існує (live — opt-in), але ось **рекомендовані** моделі, які варто регулярно перевіряти на dev-машині з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний smoke-набір (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: - OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -481,12 +478,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з інструментами + зображенням: +Запустіть gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базове покриття: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть щонайменше одну модель для кожного сімейства провайдерів: +Виберіть принаймні одну модель для кожної сім’ї провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -494,44 +491,44 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) +- Mistral: `mistral/`… (виберіть одну модель з підтримкою “tools”, яку ви маєте увімкненою) +- Cerebras: `cerebras/`… (якщо маєте доступ) +- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображень (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable варіанти тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна додати до live-матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. +Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс ті ключі, що доступні. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного agent-а: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) -- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home, якщо присутній, але це не основне сховище profile keys) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent-а, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe-и не працювали у вашому реальному host workspace. +- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах мається на увазі під “profile keys”) +- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог legacy state: `~/.openclaw/credentials/` (копіюється до staged live home, якщо наявний, але не є основним сховищем profile-key) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, legacy `credentials/` і підтримувані зовнішні каталоги CLI auth у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте виконавці Docker нижче (вони можуть змонтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). ## Live: Deepgram (транскрипція аудіо) @@ -544,14 +541,14 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа workflow ComfyUI +## Live: медіаworkflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin-ів + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin-а ## Live: генерація зображень @@ -560,23 +557,23 @@ Live-тести знаходять облікові дані так само, я - Harness: `pnpm test:live:media image` - Обсяг: - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Перед перевіркою підвантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) - - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Завантажує відсутні env-змінні провайдера з вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, тому застарілі тестові ключі в `auth-profiles.json` не маскують реальні shell credentials + - Пропускає провайдерів без придатної auth/profile/model - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, що покриваються: +- Поточні вбудовані провайдери, які охоплюються: - `openai` - `google` - Необов’язкове звуження: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Live: генерація музики @@ -584,23 +581,23 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації музики + - Перевіряє спільний шлях bundled провайдера генерації музики - Наразі охоплює Google і MiniMax - - Перед перевіркою підвантажує env-змінні провайдерів із вашої login shell (`~/.profile`) - - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, тому застарілі тестові ключі в `auth-profiles.json` не маскують реальні shell credentials + - Пропускає провайдерів без придатної auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з введенням лише prompt + - `generate` з input лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної смуги: + - Поточне покриття спільного каналу: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний прогін + - `comfy`: окремий live-файл Comfy, не ця спільна перевірка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Live: генерація відео @@ -608,166 +605,165 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації відео - - Перед перевіркою підвантажує env-змінні провайдерів із вашої login shell (`~/.profile`) - - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перевіряє спільний шлях bundled провайдера генерації відео + - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, тому застарілі тестові ключі в `auth-profiles.json` не маскують реальні shell credentials + - Пропускає провайдерів без придатної auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з введенням лише prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі buffer у спільному прогоні - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі buffer у спільному прогоні - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному прогоні: - - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддалений URL зображення + - `generate` з input лише у вигляді prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільній перевірці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільній перевірці + - Поточні `imageToVideo`-провайдери, оголошені, але пропущені у спільній перевірці: + - `vydra`, тому що bundled `veo3` підтримує лише text, а bundled `kling` вимагає віддалений image URL - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video, а також смугу `kling`, яка за замовчуванням використовує фікстуру з віддаленим URL зображення + - цей файл запускає `veo3` text-to-video плюс канал `kling`, який за замовчуванням використовує fixture із віддаленим image URL - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному прогоні: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі потребують віддалені еталонні URL `http(s)` / MP4 - - `google`, оскільки поточна спільна смуга Gemini/Veo використовує локальне введення на основі buffer, і цей шлях не приймається у спільному прогоні - - `openai`, оскільки поточна спільна смуга не гарантує доступ до video inpaint/remix, специфічний для певної організації + - Поточні `videoToVideo`-провайдери, оголошені, але пропущені у спільній перевірці: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз вимагають віддалені reference URL типу `http(s)` / MP4 + - `google`, тому що поточний спільний канал Gemini/Veo використовує локальний input на основі buffer, а цей шлях не приймається у спільній перевірці + - `openai`, тому що в поточному спільному каналі немає гарантій доступу до org-specific video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Media live harness +## Live media harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один вбудований у репозиторій entrypoint - - Автоматично підвантажує відсутні env-змінні провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один native entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth + - Повторно використовує `scripts/test-live.mjs`, тож поведінка heartbeat і quiet-mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Виконавці Docker (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці виконавці Docker поділяються на дві категорії: +Ці Docker-ранери поділяються на дві групи: -- Виконавці live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (а також підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Live-виконавці Docker за замовчуванням використовують меншу межу smoke, щоб повний прогін Docker залишався практичним: +- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з profile keys усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням мають менший smoke-ліміт, щоб повна Docker-перевірка залишалася практичною: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, + `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-смуг. -- Контейнерні smoke-виконавці: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` підіймають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібна більша вичерпна перевірка. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-каналів live. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Виконавці Docker для live-моделей також bind-mount-ять лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи host auth store: +Live-model Docker-ранери також bind-mount-ять лише потрібні CLI auth home-каталоги (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх до home-каталогу контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи host auth store: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke backend-а CLI: `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`) +- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke Codex app-server harness: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналів MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Gateway networking (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Виконавці Docker для live-моделей також bind-mount-ять поточний checkout у режимі лише читання і -підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, водночас дозволяючи запускати Vitest точно проти вашого локального source/config. -Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або -виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання -машинозалежних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe-и gateway не запускали -реальні працівники каналів Telegram/Discord тощо всередині контейнера. +Live-model Docker-ранери також bind-mount-ять поточний checkout лише для читання та +підготовлюють його у тимчасовий workdir усередині контейнера. Це робить runtime-образ +компактним, але все одно дозволяє запускати Vitest точно на ваших локальних source/config. +Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, наприклад +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні каталоги `.build` застосунків або +вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live-probes не запускали +реальні channel-воркери Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цієї Docker-смуги. +live-покриття з цього Docker-каналу. `test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint-ами, -запускає прикріплений контейнер Open WebUI проти цього gateway, виконує вхід через +контейнер OpenClaw gateway з увімкненими HTTP-endpoint-ами, сумісними з OpenAI, +запускає pinned контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантажити -image Open WebUI, а сам Open WebUI може завершувати власне налаштування холодного старту. -Ця смуга очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантажити +образ Open WebUI, а Open WebUI може потребувати завершити власний cold-start setup. +Цей канал очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(за замовчуванням `~/.profile`) є основним способом надати його у Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він підіймає seeded Gateway -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення у стилі Claude про канали + -дозволи через реальний міст stdio MCP. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP-кадри, тож smoke перевіряє те, що міст -справді випромінює, а не лише те, що певний клієнтський SDK випадково показує. +реального акаунта Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway, +стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє routed виявлення conversation, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію outbound send і channel-сповіщення + сповіщення про дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо інспектує raw stdio MCP frames, тож smoke перевіряє те, що міст +справді видає, а не лише те, що випадково показує конкретний client SDK. -Ручний ACP smoke для plain-language threads (не CI): +Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP threads, тому не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації 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_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), змонтовано в `/home/node/.npm-global` для кешованих установок CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і source-иться перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker +- Зовнішні CLI auth dirs/files у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Для звужених запусків провайдерів монтуються лише потрібні dirs/files, виведені з `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 store, а не з env +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити прикріплений tag image Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується для smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned тег образу Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку прив’язок Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Офлайн-регресії (безпечні для CI) -Це регресії «реального конвеєра» без реальних провайдерів: +Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Gateway tool calling (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent-а (Skills) +## Evals надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent-а»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності агента»: - Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесій та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- End-to-end потоки wizard, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що для Skills ще бракує (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає agent `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Ухвалення рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? +- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають спочатку залишатися детермінованими: +Майбутні evals мають спочатку залишатися детермінованими: -- Виконавець сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання skill-файлів і wiring сесій. -- Невеликий набір skill-орієнтованих сценаріїв (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live eval-и (за запитом, із керуванням через env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. +- Невеликий набір skill-орієнтованих сценаріїв (використовувати чи уникати, gate-умови, ін’єкція в prompt). +- Необов’язкові live evals (opt-in, з керуванням через env) лише після того, як буде створено безпечний для CI набір. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма plugin-а і channel-а) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітеруються по всіх виявлених plugin-ах і запускають набір -перевірок форми та поведінки. Типова unit-смуга `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте команди контрактів явно, +контракту інтерфейсу. Вони ітерують усі виявлені plugin-и й запускають набір перевірок +форми та поведінки. Типовий unit-канал `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -787,22 +783,22 @@ image Open WebUI, а сам Open WebUI може завершувати влас - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групової політики +- **directory** - API каталогу/списку учасників +- **group-policy** - Забезпечення політики групи ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe-и статусу channel -- **registry** - Форма реєстру plugin-ів +- **status** - Проби статусу channel +- **registry** - Форма registry plugin-ів ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/селекція автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/selection auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin-ів - **loader** - Завантаження plugin-ів @@ -812,21 +808,21 @@ image Open WebUI, а сам Open WebUI може завершувати влас ### Коли запускати -- Після змін експортів або subpath-ів plugin-sdk -- Після додавання чи зміни plugin-а channel або provider -- Після рефакторингу реєстрації чи виявлення plugin-ів +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin-а +- Після рефакторингу реєстрації або виявлення plugin-ів Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точне перетворення форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), робіть live-тест вузьким і таким, що вмикається через env vars -- Віддавайте перевагу найменшому шару, який виявляє помилку: - - помилка перетворення/повторного відтворення запиту provider → прямий тест моделей - - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Guardrail для обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Намагайтеся влучити в найменший шар, який ловить баг: + - баг конвертації/повторення запиту provider → direct models test + - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Захисне обмеження обходу 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, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index cd9e83d69..ff999580d 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,62 +1,55 @@ --- read_when: - - Ви хочете використовувати вбудований harness app-server Codex - - Вам потрібні посилання на модель Codex і приклади конфігурації - - Ви хочете вимкнути резервний перехід на Pi для розгортань лише з Codex -summary: Запускайте вбудовані ходи агента OpenClaw через вбудований harness app-server Codex -title: Harness Codex + - Ви хочете використовувати вбудований app-server harness Codex + - Вам потрібні посилання на моделі Codex і приклади конфігурації + - Ви хочете вимкнути резервний перехід на PI для розгортань лише з Codex +summary: Запустіть ходи вбудованого агента OpenClaw через вбудований app-server harness Codex +title: Codex Harness x-i18n: - generated_at: "2026-04-10T21:45:23Z" + generated_at: "2026-04-10T22:09:02Z" model: gpt-5.4 provider: openai - source_hash: 93aa65d08b8ffd39625d21c054856edb75a1e12d66fc7c6fae343fe398abab8b + source_hash: 71f4f8e67cfc8f573ad8f082dd4fc36ce6524f7bf235e2757117d4653cbb3d71 source_path: plugins/codex-harness.md workflow: 15 --- -# Harness Codex +# Codex Harness -Вбудований плагін `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness Pi. +Вбудований плагін `codex` дає OpenClaw змогу запускати ходи вбудованого агента через Codex app-server замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням нитки, нативною компакцією та виконанням через app-server. -OpenClaw і далі керує каналами чату, файлами сесій, вибором моделі, інструментами, -погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням thread, нативною компакцією та виконанням app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Harness вимкнено за замовчуванням. Його вибирають лише тоді, коли плагін `codex` -увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно -примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. -Якщо ви взагалі не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local -і custom-provider зберігають поточну поведінку. +Harness вимкнений за замовчуванням. Він вибирається лише тоді, коли плагін `codex` увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. +Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local і custom-provider зберігають свою поточну поведінку. ## Виберіть правильний префікс моделі OpenClaw має окремі маршрути для доступу у форматі OpenAI та Codex: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | -| `openai/gpt-5.4` | Провайдер OpenAI через механізми OpenClaw/PI | Ви хочете прямий доступ до API OpenAI Platform за допомогою `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Ви хочете ChatGPT/Codex OAuth без harness app-server Codex. | -| `codex/gpt-5.4` | Вбудований провайдер Codex плюс harness Codex | Ви хочете нативне виконання через app-server Codex для вбудованого ходу агента. | +| Model ref | Шлях runtime | Використовуйте, коли | +| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | +| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Ви хочете прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Ви хочете ChatGPT/Codex OAuth без Codex app-server harness. | +| `codex/gpt-5.4` | Вбудований провайдер Codex плюс Codex harness | Ви хочете нативне виконання Codex app-server для ходу вбудованого агента. | -Harness Codex працює лише з посиланнями на моделі `codex/*`. Наявні посилання `openai/*`, +Codex harness обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають свої звичайні шляхи. ## Вимоги - OpenClaw із доступним вбудованим плагіном `codex`. -- App-server Codex версії `0.118.0` або новішої. +- Codex app-server `0.118.0` або новіший. - Автентифікація Codex, доступна для процесу app-server. -Плагін блокує старіші або безверсійні handshake app-server. Це дає змогу -OpenClaw працювати лише з тією поверхнею протоколу, з якою його було протестовано. +Плагін блокує старіші або неверсійовані handshakes app-server. Це гарантує, що +OpenClaw працює з поверхнею протоколу, з якою його тестували. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить з `OPENAI_API_KEY`, а також -із необов’язкових файлів CLI Codex, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний -app-server Codex. +Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також +необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний Codex app-server. ## Мінімальна конфігурація @@ -98,13 +91,13 @@ app-server Codex. } ``` -Налаштування `agents.defaults.model` або моделі агента на `codex/` також +Встановлення `agents.defaults.model` або моделі агента в `codex/` також автоматично вмикає вбудований плагін `codex`. Явний запис плагіна все одно корисний у спільних конфігураціях, оскільки робить намір розгортання очевидним. -## Додайте Codex без заміни інших моделей +## Додати Codex без заміни інших моделей -Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*` і PI для +Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для всього іншого: ```json5 @@ -137,17 +130,17 @@ app-server Codex. } ``` -У такій конфігурації: +За такої конфігурації: -- `/model codex` або `/model codex/gpt-5.4` використовує harness app-server Codex. +- `/model codex` або `/model codex/gpt-5.4` використовує Codex app-server harness. - `/model gpt` або `/model openai/gpt-5.4` використовує шлях провайдера OpenAI. - `/model opus` використовує шлях провайдера Anthropic. - Якщо вибрано не-Codex модель, PI залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть резервний перехід на Pi, якщо вам потрібно довести, що кожен вбудований хід агента використовує -harness Codex: +Вимкніть резервний перехід на PI, якщо вам потрібно підтвердити, що кожен хід вбудованого агента використовує +Codex harness: ```json5 { @@ -171,13 +164,13 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо резервний перехід вимкнено, OpenClaw завершує роботу з помилкою на ранньому етапі, якщо плагін Codex вимкнено, -запитана модель не є посиланням `codex/*`, app-server надто старий або -app-server не може запуститися. +Якщо резервний перехід вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо плагін Codex вимкнено, +потрібна модель не є посиланням `codex/*`, app-server надто старий або +app-server не вдається запустити. ## Codex для окремого агента -Ви можете зробити один агент лише для Codex, тоді як типовий агент зберігатиме звичайний +Ви можете зробити одного агента Codex-only, а для агента за замовчуванням залишити звичайний автовибір: ```json5 @@ -209,14 +202,14 @@ app-server не може запуститися. } ``` -Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює власну sidecar-нитку -app-server за потреби. `/reset` очищає прив’язку сесії OpenClaw для цієї нитки. +Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову +сесію OpenClaw, а Codex harness за потреби створює або відновлює свій sidecar app-server +thread. `/reset` очищає прив’язку сесії OpenClaw для цього thread. ## Виявлення моделей За замовчуванням плагін Codex запитує app-server про доступні моделі. Якщо -виявлення не вдається або перевищує час очікування, він використовує вбудований резервний каталог: +виявлення завершується помилкою або перевищує час очікування, він використовує вбудований резервний каталог: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -242,7 +235,7 @@ app-server за потреби. `/reset` очищає прив’язку сес } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалась перевірка Codex і використовувався лише +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалась перевірка Codex і використовувався резервний каталог: ```json5 @@ -264,13 +257,13 @@ app-server за потреби. `/reset` очищає прив’язку сес ## Підключення app-server і політика -За замовчуванням плагін локально запускає Codex так: +За замовчуванням плагін локально запускає Codex командою: ```bash codex app-server --listen stdio:// ``` -Ви можете зберегти це значення за замовчуванням і налаштувати лише нативну політику Codex: +Ви можете залишити це значення за замовчуванням і налаштувати лише нативну політику Codex: ```json5 { @@ -315,22 +308,22 @@ codex app-server --listen stdio:// Підтримувані поля `appServer`: -| Поле | За замовчуванням | Значення | -| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL app-server WebSocket. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | -| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час старту/відновлення/ходу нитки. | -| `sandbox` | `"workspace-write"` | Нативний режим sandbox Codex, що надсилається під час старту/відновлення нитки. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб guardian Codex перевіряв нативні погодження. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | +| Field | Default | Значення | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | unset | URL WebSocket app-server. | +| `authToken` | unset | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | +| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається до start/resume/turn thread. | +| `sandbox` | `"workspace-write"` | Нативний режим sandbox Codex, що надсилається до start/resume thread. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Codex guardian перевіряв нативні погодження. | +| `serviceTier` | unset | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | Старі змінні середовища все ще працюють як резервні значення для локального тестування, коли -відповідне поле конфігурації не задане: +відповідне поле конфігурації не задано: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -338,9 +331,9 @@ codex app-server --listen stdio:// - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` - `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` -Для відтворюваних розгортань перевагу слід надавати конфігурації. +Для відтворюваних розгортань перевага надається конфігурації. -## Типові рецепти +## Поширені рецепти Локальний Codex зі стандартним транспортом stdio: @@ -356,7 +349,7 @@ codex app-server --listen stdio:// } ``` -Перевірка harness лише з Codex із вимкненим резервним переходом на Pi: +Перевірка harness лише для Codex, з вимкненим резервним переходом на PI: ```json5 { @@ -373,7 +366,7 @@ codex app-server --listen stdio:// } ``` -Погодження Codex із перевіркою guardian: +Погодження Codex, що перевіряються guardian: ```json5 { @@ -394,7 +387,7 @@ codex app-server --listen stdio:// } ``` -Віддалений app-server із явними заголовками: +Віддалений app-server з явними заголовками: ```json5 { @@ -417,74 +410,78 @@ codex app-server --listen stdio:// } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано -до наявної нитки Codex, наступний хід знову надсилає до +Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw прив’язано +до наявного Codex thread, наступний хід знову надсилає до app-server поточну вибрану модель `codex/*`, провайдера, політику погодження, sandbox і service tier. -Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку -нитки, але просить Codex продовжити роботу з новою вибраною моделлю. +Перехід з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку до +thread, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex Вбудований плагін реєструє `/codex` як авторизовану slash-команду. Вона є -універсальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. +універсальною і працює на будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та Skills. -- `/codex models` показує список живих моделей app-server Codex. -- `/codex threads [filter]` показує список нещодавніх ниток Codex. -- `/codex resume ` приєднує поточну сесію OpenClaw до наявної нитки Codex. -- `/codex compact` просить app-server Codex стиснути приєднану нитку. -- `/codex review` запускає нативну перевірку Codex для приєднаної нитки. +- `/codex status` показує в реальному часі підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP servers і skills. +- `/codex models` виводить список моделей Codex app-server у реальному часі. +- `/codex threads [filter]` виводить список нещодавніх thread Codex. +- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного thread Codex. +- `/codex compact` просить Codex app-server виконати компакцію прив’язаного thread. +- `/codex review` запускає нативну перевірку Codex для прив’язаного thread. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` показує список станів MCP-серверів app-server Codex. -- `/codex skills` показує список Skills app-server Codex. +- `/codex mcp` показує стан MCP server Codex app-server. +- `/codex skills` виводить список skills Codex app-server. -`/codex resume` записує той самий файл sidecar-прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цю нитку Codex, передає -поточну вибрану модель OpenClaw `codex/*` до app-server і зберігає +`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає +поточну вибрану в OpenClaw модель `codex/*` до app-server і зберігає увімкнену розширену історію. +Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Для окремих +методів керування повідомляється `unsupported by this Codex app-server`, якщо +майбутній або кастомний app-server не надає цей метод JSON-RPC. + ## Інструменти, медіа та компакція -Harness Codex змінює лише низькорівневий виконавець вбудованого агента. +Codex harness змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі формує список інструментів і отримує динамічні результати інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень +OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями і далі проходять через звичайний шлях доставки OpenClaw. -Коли вибрана модель використовує harness Codex, нативна компакція нитки -делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +Коли вибрана модель використовує Codex harness, нативна компакція thread делегується +Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -аналіз медіа й далі використовують відповідні налаштування провайдера/моделі, як-от +розуміння медіа продовжують використовувати відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення проблем +## Усунення неполадок **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw переходить на резервний Pi:** задайте `embeddedHarness.fallback: "none"` або +**OpenClaw переходить на PI:** задайте `embeddedHarness.fallback: "none"` або `OPENCLAW_AGENT_HARNESS_FALLBACK=none` під час тестування. -**App-server відхиляється:** оновіть Codex, щоб handshake app-server +**app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений app-server підтримує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і те, що віддалений app-server використовує ту саму версію протоколу Codex app-server. -**Не-Codex модель використовує PI:** це очікувано. Harness Codex працює лише з -посиланнями на моделі `codex/*`. +**Не-Codex модель використовує PI:** це очікувана поведінка. Codex harness обробляє лише +посилання на моделі `codex/*`. -## Пов’язано +## Пов’язане -- [Плагіни harness агента](/uk/plugins/sdk-agent-harness) +- [Плагіни Agent Harness](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke)