From edb70acf472c1d93a1268f67a03407100705ed89 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 23:18:49 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 665 ++++++++++++++------------- docs/uk/plugins/codex-harness.md | 202 ++++---- docs/uk/plugins/sdk-agent-harness.md | 156 ++++--- 3 files changed, 541 insertions(+), 482 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 583b04958..2c1bd5dc8 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделей/провайдерів - - Налагодження поведінки gateway + agent -summary: 'Набір для тестування: модульні/e2e/live набори, Docker-ранери та що охоплює кожен тест' + - Додавання регресій для помилок моделі/провайдера + - Налагодження поведінки gateway + агента +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та те, що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-10T22:46:12Z" + generated_at: "2026-04-10T23:15:01Z" model: gpt-5.4 provider: openai - source_hash: cc286815c4fb75925ddbc764470c5263bb51bfd3675020e8cc232e3ffd4315fe + source_hash: 1ef760f5cc65d0c0eaf0113350a870ba76e1b40b6754f949b53ed62e7e1e92bd source_path: help/testing.md workflow: 15 --- @@ -18,12 +18,12 @@ x-i18n: OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. -Цей документ є керівництвом «як ми тестуємо»: +Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) -- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами +- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів +- Як додавати регресії для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -32,8 +32,8 @@ 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-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` @@ -45,121 +45,121 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через env-змінні allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. ## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або до кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старого послідовного lane. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або до кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішого послідовного lane. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA-набір у тимчасовій Multipass Linux VM. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски перенаправляють підтримувані QA auth inputs, які практично використовувати в гостьовій системі: - ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайний QA-звіт і підсумок, а також Multipass-логи в + - Під час live-запусків пересилає підтримувані QA auth inputs, які практично використовувати в guest: + env-based provider keys, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. + - Записує звичайний QA-звіт і summary, а також Multipass-логи до `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає QA-сайт на базі Docker для QA-роботи в стилі оператора. -## Набори тестів (що і де запускається) +## Набори тестів (що де запускається) -Сприймайте набори як такі, що мають «зростаючий реалізм» (і зростаючу нестабільність/вартість): +Сприймайте набори як «зростаючий реалізм» (і зростаючу нестабільність/вартість): ### Unit / integration (за замовчуванням) - Команда: `pnpm test` - Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` -- Охоплення: +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` +- Обсяг: - Чисті unit-тести - - Інтеграційні тести в межах процесу (gateway auth, routing, tooling, parsing, config) + - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - Примітка про projects: - - Нетаргетований `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує пікове RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує граф projects у native root `vitest.config.ts`, оскільки multi-shard watch loop є непрактичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спрямовують явні цілі file/directory спочатку через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; редагування config/setup усе ще повертаються до ширшого повторного запуску root project. - - Легкі unit-тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних чистих utility-областей спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files залишаються на наявних lanes. - - Вибрані helper source files `plugin-sdk` і `commands` також зіставляють changed-mode runs з явними сусідніми тестами в цих легких lanes, щоб редагування helpers не запускали повторно весь важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі bucket-и: top-level core helpers, top-level інтеграційні тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти в дешеві тести status/chunk/token. + - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard watch-цикл непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не сплачує повну ціну запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; правки config/setup, як і раніше, повертаються до широкого повторного запуску root-project. + - Легкі щодо імпорту unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних суто утилітарних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper source-файли `plugin-sdk` і `commands` також відображають changed-mode запуски на явні sibling-тести в цих легких lanes, тож редагування helpers не змушує повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration-тести і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness для reply із дешевих тестів status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте inputs виявлення message-tool або runtime context compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime context для compaction, зберігайте обидва рівні покриття. - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте в здоровому стані інтеграційні набори embedded runner: + - Також підтримуйте в здоровому стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction як і раніше проходять + - Ці набори перевіряють, що scoped ids і поведінка compaction, як і раніше, проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих інтеграційних шляхів. + достатньою заміною для цих integration-шляхів. - Примітка про pool: - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. - - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер також працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі значення `threads` + `isolate: false` із спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm test:changed` спрямовується через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live configs. + - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. + - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` зі спільної конфігурації Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо вам потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидкі локальні ітерації: + - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чисто відображаються на менший набір. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автоматичне локальне масштабування workers тепер навмисно більш консервативне й також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб changed-mode reruns залишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. + - Автоматичне локальне масштабування workers тепер навмисно більш консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - Примітка про perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс import-breakdown output. - - `pnpm test:perf:imports:changed` звужує той самий вид профілювання до файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує main-thread CPU profile для startup і transform overhead у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles раннера для unit-набору з вимкненим file parallelism. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту разом із виводом розбивки імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий вид профілювання файлами, зміненими від `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього закоміченого diff і виводить wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує main-thread CPU profile для накладних витрат запуску й transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим file parallelism. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові налаштування runtime: +- Значення runtime за замовчуванням: - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати на console I/O. + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути детальний console output. -- Охоплення: - - Наскрізна поведінка multi-instance gateway - - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. +- Обсяг: + - End-to-end поведінка multi-instance gateway + - WebSocket/HTTP surfaces, node pairing і важча мережева взаємодія - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) ### E2E: smoke для бекенда OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Охоплення: - - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile +- Обсяг: + - Запускає ізольований gateway OpenShell на хості через Docker + - Створює sandbox з тимчасового локального Dockerfile - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Потрібен локальний CLI `openshell` і справний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test 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 binary або wrapper script ### Live (реальні провайдери + реальні моделі) @@ -167,142 +167,142 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Охоплення: +- Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін форматів у провайдерів, особливостей tool-calling, проблем auth і поведінки rate limit + - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки rate limit - Очікування: - - Навмисно не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски підвантажують `~/.profile`, щоб підібрати відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли ви свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає progress output `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація 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 responses. -- Вивід progress/heartbeat: - - Live-набори тепер виводять progress lines у stderr, тож під час тихого захоплення консолі Vitest видно, що довгі виклики провайдера залишаються активними. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб progress lines провайдера/gateway транслювалися негайно під час live-запусків. - - Налаштовуйте direct-model heartbeats через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeats gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material до тимчасового test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний home directory. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи bootstrap gateway / Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні startup-логи. +- Ротація API keys (специфічна для провайдера): установіть `*_API_KEYS` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на rate limit. +- Вивід прогресу/heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, тож тривалі виклики провайдера залишаються помітно активними, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. + - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато змінили) -- Зміни в gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагодження «мій бот не працює» / відмов, специфічних для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запустіть звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: огляд capability Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, що наразі оголошена** підключеним Android node, і перевірити поведінку контракту команд. -- Охоплення: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить застосунок). - - Перевірка `node.invoke` у gateway для кожної команди для вибраного Android node. -- Обов’язкова попередня підготовка: - - Android-застосунок уже підключений і pair-ений до gateway. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android node, і перевірити поведінку контракту команди. +- Обсяг: + - Попередньо підготовлений/ручний setup (набір не встановлює/не запускає/не pair-ить застосунок). + - Перевірка gateway `node.invoke` команда за командою для вибраного Android node. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключений і pair-ений із gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. + - Надано дозволи/згоду на capture для capabilities, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: model smoke (ключі профілів) +## Live: smoke для моделі (profile keys) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб ми могли ізолювати збої: -- «Direct model» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). +- «Direct model» показує, чи взагалі провайдер/модель може відповісти з наданим ключем. +- «Gateway smoke» показує, що повний конвеєр gateway+agent працює для цієї моделі (sessions, history, tools, sandbox policy тощо). ### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перерахувати виявлені моделі + - Перелічити виявлені моделі - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви запускаєте Vitest безпосередньо) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався сфокусованим на gateway smoke - Як вибирати моделі: - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` є псевдонімом для modern allowlist - - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для перевірок modern/all за замовчуванням використовується curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (comma allowlist) + - Sweeps modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. - Як вибирати провайдерів: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і запасні env-джерела - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: profile store та env fallbacks + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламаний / ключ недійсний» від «зламаний конвеєр gateway agent» - - Містить малі ізольовані регресії (наприклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відокремлює «provider API зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: Gateway + dev agent smoke (те, що насправді робить "@openclaw") +### Шар 2: Gateway + dev agent smoke (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти gateway у межах процесу - - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі-з-ключами й перевіряти: + - Підняти in-process gateway + - Створити/пропатчити session `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітеруватися по models-with-keys і перевіряти: - «змістовну» відповідь (без tools) - - що працює реальний виклик tool (read probe) - - необов’язкові додаткові перевірки tools (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probes (щоб ви могли швидко пояснювати збої): - - probe `read`: тест записує nonce-файл у workspace і просить agent виконати `read` цього файлу та повернути nonce. - - probe `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що реальний виклик tool працює (read probe) + - необов’язкові додаткові tool probes (exec+read probe) + - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить agent `read` його та повернути nonce у відповіді. + - `exec+read` probe: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім зчитати його назад через `read`. + - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви запускаєте Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` є псевдонімом для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway-перевірок за замовчуванням використовується curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникнути «весь OpenRouter»): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або comma list), щоб звузити набір + - Sweeps modern/all для gateway за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. +- Як вибирати провайдерів (уникайте «OpenRouter everything»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (comma allowlist) - Tool + image probes у цьому live-тесті завжди ввімкнені: - - probe `read` + probe `exec+read` (навантаження на tools) - - image probe запускається, коли модель оголошує підтримку image input + - `read` probe + `exec+read` probe (tool stress) + - image probe запускається, коли модель оголошує підтримку введення зображень - Потік (на високому рівні): - - Тест генерує маленький PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допускається OCR tolerance: незначні помилки) + - Embedded agent передає мультимодальне повідомлення користувача до моделі + - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки допускаються) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете протестувати на своїй машині (і точні `provider/model` id), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke для CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не торкаючись вашого типового config. +- Мета: перевірити конвеєр 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` -- Типові значення: - - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin власника CLI backend. +- Значення за замовчуванням: + - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` + - Поведінка 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`, щоб надіслати реальне image attachment (шляхи підставляються у prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до image-файлів як CLI args замість підстановки в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб контролювати спосіб передавання image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої session при переході Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи додаються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як CLI args замість вставлення в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання args для зображень, коли задано `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності тієї самої session Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль переключення). Приклад: @@ -318,7 +318,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -330,27 +330,27 @@ pnpm test:docker:live-cli-backend:gemini Примітки: - Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він отримує метадані smoke CLI з extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносимий Claude Code subscription OAuth через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить роботу прямого `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Цей lane підписки за замовчуванням вимикає probes Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів плану підписки. -- Live smoke CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик MCP tool `cron`, перевірений через gateway CLI. -- Типовий smoke для Claude також оновлює session із Sonnet до Opus і перевіряє, що відновлена session все ще пам’ятає попередню нотатку. +- Він запускає live smoke для CLI-backend всередині Docker-образу репозиторію від імені не-root користувача `node`. +- Він визначає метадані CLI smoke з extension-власника, потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить, що прямий `claude -p` у Docker працює, а потім виконує два ходи Gateway CLI-backend без збереження env vars Anthropic API key. Цей subscription lane за замовчуванням вимикає Claude MCP/tool і image probes, тому що Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів subscription plan. +- Live smoke для CLI-backend тепер перевіряє той самий end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик MCP tool `cron`, перевірений через gateway CLI. +- Типовий smoke для Claude також патчить session із Sonnet на Opus і перевіряє, що відновлена session усе ще пам’ятає попередню нотатку. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke для ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік ACP conversation-bind з live ACP agent: +- Мета: перевірити реальний flow conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати synthetic conversation message-channel на місці - - надіслати звичайне follow-up повідомлення в тій самій conversation - - перевірити, що follow-up потрапляє до transcript прив’язаної ACP session + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайний follow-up у тій самій conversation + - перевірити, що follow-up потрапляє до транскрипту прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Типові значення: +- Значення за замовчуванням: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Synthetic channel: контекст conversation у стилі Slack DM + - Синтетичний channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -359,7 +359,7 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Цей lane використовує поверхню gateway `chat.send` з synthetic originating-route fields лише для адміністраторів, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. + - Цей lane використовує surface gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agents plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -376,7 +376,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent: +Docker-рецепти для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -387,30 +387,30 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: - Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- За замовчуванням він запускає smoke для ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, переносить відповідний auth material CLI до контейнера, встановлює `acpx` у записуваний npm prefix, а потім за потреби встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). -- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підвантаженого профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, підготовлює відповідні auth material CLI у контейнері, встановлює `acpx` у записуваний npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо він відсутній. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env vars провайдера з підключеного profile доступними для дочірнього harness CLI. -## Live: smoke harness app-server Codex +## Live: smoke для harness app-server Codex -- Мета: перевірити harness Codex, що належить plugin, через звичайний метод gateway - `agent`: +- Мета: перевірити Codex harness, яким володіє plugin, через звичайний gateway + метод `agent`: - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - надіслати другий хід до тієї самої session OpenClaw і перевірити, що потік app-server може відновитися - - запустити `/codex status` і `/codex models` через той самий шлях команд - gateway + - запустити `/codex status` і `/codex models` через той самий шлях gateway + command - Тест: `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` +- Модель за замовчуванням: `codex/gpt-5.4` +- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти, тихо переключившись на PI. -- Auth: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані + harness не міг пройти тест, тихо переключившись на PI. +- Auth: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -434,46 +434,49 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: - Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли auth - Codex CLI, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth Codex CLI, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm prefix, підготовлює source tree, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням вмикає image та MCP/tool probes. Установіть +- Docker за замовчуванням вмикає image і MCP/tool probes. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли вам потрібен вужчий debug run. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, узгоджено з live + конфігурацією тесту, щоб fallback на `openai-codex/*` або PI не міг приховати регресію + Codex harness. ### Рекомендовані live-рецепти -Вузькі явні allowlist найшвидші й найменш схильні до нестабільності: +Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: -- Одна модель, direct (без gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling для кількох провайдерів: +- Tool calling через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (ключ Gemini API + Antigravity): +- Фокус на Google (Gemini API key + 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 агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окремий auth і особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений у Google Gemini API через HTTP (API key / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний binary `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний binary `gemini`; він має власний auth і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «списку моделей CI» (live — це opt-in), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Немає фіксованого «CI model list» (live — це opt-in), але це **рекомендовані** моделі, які слід регулярно покривати на dev machine з ключами. -### Сучасний smoke-набір (tool calling + image) +### Modern smoke set (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: +Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -483,12 +486,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустити gateway smoke з tools + image: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Baseline: 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`) @@ -503,37 +506,37 @@ pnpm test:docker:live-codex-harness - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (attachment → multimodal message) -Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable variants тощо), щоб перевірити image probe. -### Aggregators / альтернативні gateway +### Aggregators / alternate gateways Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/config): +Більше провайдерів, які можна включити до live matrix (якщо у вас є облікові дані/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + доступні ключі. +Порада: не намагайтеся жорстко фіксувати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як це робить CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. -- Auth-профілі для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означають «ключі профілів» у live-тестах) +- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог legacy state: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, legacy `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. +- Каталог legacy state: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile keys) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для окремих агентів, legacy `credentials/` і підтримувані зовнішні CLI auth dirs до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` в контейнер). ## Live: Deepgram (транскрипція аудіо) @@ -546,31 +549,31 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа workflows ComfyUI +## Live: media для 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` - - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації plugin +- Обсяг: + - Перевіряє bundled шляхи Comfy для зображень, відео і `music_generate` + - Пропускає кожну capability, якщо `models.providers.comfy.` не налаштовано + - Корисно після змін у submission workflow Comfy, polling, downloads або реєстрації plugin ## Live: генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` -- Охоплення: - - Перераховує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API-ключам над збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime capability: +- Обсяг: + - Перелічує кожен зареєстрований provider plugin для генерації зображень + - Перед probes завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатного auth/profile/model + - Запускає стандартні варіанти генерації зображень через shared runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, що охоплюються: +- Поточні bundled провайдери, які охоплюються: - `openai` - `google` - Необов’язкове звуження: @@ -578,71 +581,71 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Live: генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` -- Охоплення: - - Перевіряє спільний вбудований шлях провайдера генерації музики +- Обсяг: + - Перевіряє спільний bundled шлях provider-а генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API-ключам над збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` з input лише у вигляді prompt + - Перед probes завантажує env vars провайдерів із вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатного auth/profile/model + - Запускає обидва заявлені runtime modes, коли вони доступні: + - `generate` із вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Live: генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` -- Охоплення: - - Перевіряє спільний вбудований шлях провайдера генерації відео - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API-ключам над збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` з input лише у вигляді prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільній перевірці - - Поточні провайдери `imageToVideo`, що оголошені, але пропускаються у спільній перевірці: - - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений image URL +- Обсяг: + - Перевіряє спільний bundled шлях provider-а генерації відео + - Перед probes завантажує env vars провайдера з вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатного auth/profile/model + - Запускає обидва заявлені runtime modes, коли вони доступні: + - `generate` із вхідними даними лише у вигляді prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає buffer-backed локальне введення зображення в shared sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає buffer-backed локальне введення відео в shared sweep + - Поточні провайдери `imageToVideo`, які оголошені, але пропускаються в shared sweep: + - `vydra`, тому що bundled `veo3` є лише текстовим, а bundled `kling` вимагає remote image URL - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує фікстуру віддаленого image URL + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture віддаленого image URL - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, що оголошені, але пропускаються у спільній перевірці: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені референсні URL `http(s)` / MP4 - - `google`, оскільки поточний спільний lane Gemini/Veo використовує локальний input на основі buffer, а цей шлях не приймається у спільній перевірці - - `openai`, оскільки поточний спільний lane не гарантує наявність org-specific доступу до video inpaint/remix + - Поточні провайдери `videoToVideo`, які оголошені, але пропускаються в shared sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають reference URLs віддалених `http(s)` / MP4 + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальне buffer-backed введення, а цей шлях не приймається в shared sweep + - `openai`, тому що поточний shared lane не гарантує доступ до org-specific video inpaint/remix - Необов’язкове звуження: - `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"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - Автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth, за замовчуванням - - Повторно використовує `scripts/test-live.mjs`, тож поведінка heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори image, music і video через один repo-native entrypoint + - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатний auth + - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet-mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -651,125 +654,125 @@ Live-тести знаходять облікові дані так само, я ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці 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 dir і workspace (і підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Live Docker-ранери за замовчуванням мають менший smoke cap, щоб повна Docker-перевірка залишалася практичною: +- Ранери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний config dir і workspace (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker-ранери live за замовчуванням використовують менший smoke cap, щоб повний Docker sweep залишався практичним: `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-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker lanes. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, і + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли + вам свідомо потрібне більше вичерпне сканування. +- `test:docker:all` один раз будує live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lanes live. +- Ранери container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або більше реальних контейнерів і перевіряють шляхи інтеграції вищого рівня. -Live-model Docker-ранери також bind-mount лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без змін у host auth store: +Docker-ранери live-model також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени, не змінюючи auth store хоста: - Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke для ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke для CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke для harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - 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`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер onboarding (TTY, full scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережева взаємодія gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст channel MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (install smoke + alias `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Live-model Docker-ранери також bind-mount-ять поточний checkout у режимі лише читання і +Docker-ранери live-model також bind-mount-ять поточний checkout лише для читання і підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно дозволяє запускати Vitest точно на вашому локальному source/config. -Під час підготовки пропускаються великі локальні кеші та результати збірки застосунків, такі як +image компактним, але водночас дає змогу запускати Vitest на вашому точному локальному source/config. +Крок staging пропускає великі локальні кеші та результати збирання застосунків, такі як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -Gradle output, щоб Docker live-запуски не витрачали хвилини на копіювання +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали -реальні channel workers Telegram/Discord тощо всередині контейнера. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали +реальні workers channel для Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway live-покриття з цього Docker lane. -`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, +запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat request через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити -image Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. -Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — основний спосіб передати його у Dockerized runs. -Успішні запуски виводять невеликий JSON payload на зразок `{ "ok": true, "model": +реальний chat request через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися витягнути +image Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. +Цей lane очікує придатний live model key, і `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) є основним способом надати його під час Dockerized запусків. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального акаунта Telegram, Discord або iMessage. Він піднімає seeded контейнер -Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord чи iMessage. Він запускає seeded Gateway +контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення conversation із маршрутизацією, читання transcript, metadata вкладень, -поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує raw stdio MCP frames, тож smoke перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує конкретний client SDK. +поведінку live event queue, outbound send routing і channel-сповіщення в стилі Claude + +сповіщення про permissions через реальний stdio MCP bridge. Перевірка notifications +напряму аналізує raw stdio MCP frames, тож smoke перевіряє те, що міст +фактично випромінює, а не лише те, що випадково відображає конкретний client SDK. -Ручний ACP smoke thread plain-language (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для workflow регресій/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. -Корисні env-змінні: +Корисні env vars: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підвантажується перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI у Docker -- Зовнішні каталоги/файли auth CLI у `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - - Типові каталоги: `.minimax` - - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` +- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні CLI auth dirs/files у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів + - Каталоги за замовчуванням: `.minimax` + - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків без потреби в новій збірці -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібне перевизначення збірки +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів, а не з env - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt для перевірки nonce, який використовується у smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag image Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте перевірки документації після змін у документації: `pnpm check:docs`. Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечні для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Tool calling gateway (мок OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, записує config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Tool calling через gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер gateway (WS `wizard.start`/`wizard.next`, примусово записує config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Оцінювання надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Мок tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесій і ефекти config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring session і effects config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає agent `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/args? -- **Контракти workflow:** багатохідові сценарії, які перевіряють порядок tools, перенесення history сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає agent `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення history сесії та межі sandbox. -Майбутні evals мають залишатися насамперед детермінованими: +Майбутні evals мають насамперед залишатися детермінованими: -- Ранер сценаріїв із mock providers для перевірки tool calls + порядку, читання skill files і wiring сесій. -- Невеликий набір сценаріїв, орієнтованих на skills (використовувати чи уникати, gating, ін’єкція в prompt). -- Необов’язкові live evals (opt-in, із gate через env) лише після того, як буде готовий безпечний для CI набір. +- Ранер сценаріїв із mock providers для перевірки tool calls + порядку, читання файлів skill і wiring session. +- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live evals (opt-in, з env-gating) лише після того, як безпечний для CI набір буде готовий. ## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір перевірок -форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні файли seam і smoke; запускайте контрактні команди явно, +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму контракту інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -789,14 +792,14 @@ Gateway, запускає другий контейнер, який піднім - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/списку учасників +- **directory** - API каталогу/реєстру - **group-policy** - Застосування групової політики -### Контракти стану provider +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel +- **status** - Probes статусу channel - **registry** - Форма реєстру plugin ### Контракти provider @@ -804,7 +807,7 @@ Gateway, запускає другий контейнер, який піднім Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/selection auth +- **auth-choice** - Вибір/селекція auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin @@ -814,21 +817,21 @@ Gateway, запускає другий контейнер, який піднім ### Коли запускати -- Після зміни export-ів або subpath-ів plugin-sdk -- Після додавання або зміни plugin channel або provider +- Після змін у exports або subpaths `plugin-sdk` +- Після додавання або зміни plugin channel чи provider - Після рефакторингу реєстрації plugin або виявлення -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. -## Додавання регресій (рекомендації) +## Додавання регресій (настанови) Коли ви виправляєте проблему provider/model, виявлену в live: -- Додавайте безпечну для CI регресію, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), зберігайте live-тест вузьким і opt-in через env-змінні -- Віддавайте перевагу найменшому шару, який ловить баг: - - баг конвертації/повторення запиту provider → тест direct models - - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Guardrail для обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу найменшому шару, який виявляє баг: + - баг перетворення/відтворення запиту provider → тест direct models + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Захисне правило обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить один вибраний target на кожен клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. + - Якщо ви додаєте нову родину target SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується невдачею на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index ff999580d..1c435c986 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,59 +1,66 @@ --- read_when: - - Ви хочете використовувати вбудований app-server harness Codex + - Ви хочете використовувати вбудований каркас app-server Codex - Вам потрібні посилання на моделі Codex і приклади конфігурації - - Ви хочете вимкнути резервний перехід на PI для розгортань лише з Codex -summary: Запустіть ходи вбудованого агента OpenClaw через вбудований app-server harness Codex -title: Codex Harness + - Ви хочете вимкнути резервний перехід на Pi для розгортань лише з Codex +summary: Запускайте вбудовані ходи агента OpenClaw через вбудований каркас app-server Codex +title: Каркас Codex x-i18n: - generated_at: "2026-04-10T22:09:02Z" + generated_at: "2026-04-10T23:15:03Z" model: gpt-5.4 provider: openai - source_hash: 71f4f8e67cfc8f573ad8f082dd4fc36ce6524f7bf235e2757117d4653cbb3d71 + source_hash: 60e1dcf4f1a00c63c3ef31d72feac44bce255421c032c58fa4fd67295b3daf23 source_path: plugins/codex-harness.md workflow: 15 --- -# Codex Harness +# Каркас Codex -Вбудований плагін `codex` дає OpenClaw змогу запускати ходи вбудованого агента через Codex app-server замість вбудованого harness PI. +Вбудований плагін `codex` дає OpenClaw змогу запускати вбудовані ходи агента через +app-server Codex замість вбудованого каркаса PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням thread, нативною компакцією та виконанням app-server. -OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням потоку, нативною компакцією та виконанням через app-server. +OpenClaw і надалі керує каналами чату, файлами сесій, вибором моделі, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом стенограми. -Harness вимкнений за замовчуванням. Він вибирається лише тоді, коли плагін `codex` увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. -Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local і custom-provider зберігають свою поточну поведінку. +Цей каркас вимкнений за замовчуванням. Його буде вибрано лише тоді, коли плагін `codex` +увімкнений і розв’язана модель є моделлю `codex/*`, або коли ви явно примусово задаєте +`embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. +Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local +і custom-provider зберігають свою поточну поведінку. ## Виберіть правильний префікс моделі -OpenClaw має окремі маршрути для доступу у форматі OpenAI та Codex: +OpenClaw має окремі маршрути для доступу у стилі OpenAI і 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 для ходу вбудованого агента. | +| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | +| ------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | +| `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 без каркаса app-server Codex. | +| `codex/gpt-5.4` | Вбудований провайдер Codex плюс каркас Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. | -Codex harness обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, +Каркас Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають свої звичайні шляхи. ## Вимоги - OpenClaw із доступним вбудованим плагіном `codex`. -- Codex app-server `0.118.0` або новіший. -- Автентифікація Codex, доступна для процесу app-server. +- app-server Codex версії `0.118.0` або новішої. +- Доступна автентифікація Codex для процесу app-server. -Плагін блокує старіші або неверсійовані handshakes app-server. Це гарантує, що -OpenClaw працює з поверхнею протоколу, з якою його тестували. +Плагін блокує старіші або неверсіоновані узгодження app-server. Це утримує +OpenClaw на поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також -необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний Codex app-server. +Для живих і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також +з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, які використовує +ваш локальний app-server Codex. ## Мінімальна конфігурація -Використовуйте `codex/gpt-5.4`, увімкніть вбудований плагін і примусово задайте harness `codex`: +Використовуйте `codex/gpt-5.4`, увімкніть вбудований плагін і примусово задайте каркас `codex`: ```json5 { @@ -76,7 +83,7 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -91,13 +98,13 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -Встановлення `agents.defaults.model` або моделі агента в `codex/` також +Установлення `agents.defaults.model` або моделі агента в `codex/` також автоматично вмикає вбудований плагін `codex`. Явний запис плагіна все одно корисний у спільних конфігураціях, оскільки робить намір розгортання очевидним. -## Додати Codex без заміни інших моделей +## Додайте Codex без заміни інших моделей -Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для +Залиште `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI для всього іншого: ```json5 @@ -130,17 +137,17 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -За такої конфігурації: +Із такою структурою: -- `/model codex` або `/model codex/gpt-5.4` використовує Codex app-server harness. +- `/model codex` або `/model codex/gpt-5.4` використовує каркас app-server Codex. - `/model gpt` або `/model openai/gpt-5.4` використовує шлях провайдера OpenAI. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не-Codex модель, PI залишається harness сумісності. +- Якщо вибрано не-Codex модель, PI залишається каркасом сумісності. ## Розгортання лише з Codex -Вимкніть резервний перехід на PI, якщо вам потрібно підтвердити, що кожен хід вбудованого агента використовує -Codex harness: +Вимкніть резервний перехід на PI, якщо вам потрібно підтвердити, що кожен вбудований хід агента використовує +каркас Codex: ```json5 { @@ -166,11 +173,11 @@ openclaw gateway run Якщо резервний перехід вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо плагін Codex вимкнено, потрібна модель не є посиланням `codex/*`, app-server надто старий або -app-server не вдається запустити. +app-server не може запуститися. ## Codex для окремого агента -Ви можете зробити одного агента Codex-only, а для агента за замовчуванням залишити звичайний +Ви можете зробити одного агента лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний автовибір: ```json5 @@ -203,13 +210,13 @@ app-server не вдається запустити. ``` Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а Codex harness за потреби створює або відновлює свій sidecar app-server -thread. `/reset` очищає прив’язку сесії OpenClaw для цього thread. +сесію OpenClaw, а каркас Codex за потреби створює або відновлює свій побічний потік app-server. +`/reset` очищає прив’язку сесії OpenClaw для цього потоку. ## Виявлення моделей За замовчуванням плагін Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або перевищує час очікування, він використовує вбудований резервний каталог: +виявлення завершується помилкою або перевищує час очікування, використовується вбудований резервний каталог: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -235,7 +242,7 @@ thread. `/reset` очищає прив’язку сесії OpenClaw для ц } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалась перевірка Codex і використовувався +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалася перевірка Codex і використовувався резервний каталог: ```json5 @@ -255,9 +262,9 @@ thread. `/reset` очищає прив’язку сесії OpenClaw для ц } ``` -## Підключення app-server і політика +## Підключення до app-server і політика -За замовчуванням плагін локально запускає Codex командою: +За замовчуванням плагін локально запускає Codex так: ```bash codex app-server --listen stdio:// @@ -308,22 +315,22 @@ codex app-server --listen stdio:// Підтримувані поля `appServer`: -| 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"`. | +| Поле | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------- | +| `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` | Час очікування для викликів площини керування app-server. | +| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається до start/resume/turn потоку. | +| `sandbox` | `"workspace-write"` | Нативний режим sandbox Codex, що надсилається до start/resume потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб нативні погодження переглядав guardian Codex. | +| `serviceTier` | unset | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | Старі змінні середовища все ще працюють як резервні значення для локального тестування, коли -відповідне поле конфігурації не задано: +відповідне поле конфігурації не задане: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -335,7 +342,7 @@ codex app-server --listen stdio:// ## Поширені рецепти -Локальний Codex зі стандартним транспортом stdio: +Локальний Codex із типовим транспортом stdio: ```json5 { @@ -349,7 +356,7 @@ codex app-server --listen stdio:// } ``` -Перевірка harness лише для Codex, з вимкненим резервним переходом на PI: +Перевірка каркаса лише Codex, із вимкненим резервним переходом на PI: ```json5 { @@ -366,7 +373,7 @@ codex app-server --listen stdio:// } ``` -Погодження Codex, що перевіряються guardian: +Погодження Codex із переглядом guardian: ```json5 { @@ -387,7 +394,7 @@ codex app-server --listen stdio:// } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -410,78 +417,79 @@ codex app-server --listen stdio:// } ``` -Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw прив’язано -до наявного Codex thread, наступний хід знову надсилає до -app-server поточну вибрану модель `codex/*`, провайдера, політику погодження, sandbox і service tier. -Перехід з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку до -thread, але просить Codex продовжити з новою вибраною моделлю. +Перемикання моделей і далі контролює OpenClaw. Коли сесію OpenClaw прив’язано +до наявного потоку Codex, наступний хід знову надсилає до +app-server поточні вибрані `codex/*` модель, провайдера, політику погодження, sandbox і service tier. +Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку +до потоку, але просить Codex продовжити з нововибраною моделлю. ## Команда Codex Вбудований плагін реєструє `/codex` як авторизовану slash-команду. Вона є -універсальною і працює на будь-якому каналі, що підтримує текстові команди OpenClaw. +загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/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 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 account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` показує стан MCP server Codex app-server. -- `/codex skills` виводить список skills Codex app-server. +- `/codex mcp` перелічує стан серверів MCP app-server Codex. +- `/codex skills` перелічує Skills app-server Codex. -`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає -поточну вибрану в OpenClaw модель `codex/*` до app-server і зберігає -увімкнену розширену історію. +`/codex resume` записує той самий файл побічної прив’язки, який каркас використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає поточну +вибрану в OpenClaw модель `codex/*` до app-server і зберігає ввімкнену +розширену історію. -Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Для окремих -методів керування повідомляється `unsupported by this Codex app-server`, якщо +Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Для окремих +методів керування буде показано `unsupported by this Codex app-server`, якщо майбутній або кастомний app-server не надає цей метод JSON-RPC. ## Інструменти, медіа та компакція -Codex harness змінює лише низькорівневий виконавець вбудованого агента. +Каркас Codex змінює лише низькорівневий виконавець вбудованого агента. OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями +каркаса. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями і далі проходять через звичайний шлях доставки OpenClaw. -Коли вибрана модель використовує Codex harness, нативна компакція thread делегується -Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. +Коли вибрана модель використовує каркас Codex, нативна компакція потоку делегується app-server Codex. +OpenClaw зберігає дзеркало стенограми для історії каналу, пошуку, `/new`, `/reset` і майбутнього +перемикання моделі або каркаса. Дзеркало включає запит користувача, фінальний текст помічника та +полегшені записи міркувань або плану Codex, коли app-server їх надсилає. Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа продовжують використовувати відповідні налаштування провайдера/моделі, такі як +аналіз медіа й надалі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення неполадок +## Усунення несправностей **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, -задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. +задайте посилання на модель `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 -повідомляв версію `0.118.0` або новішу. +**app-server відхиляється:** оновіть Codex, щоб узгодження app-server +повідомляло версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений app-server використовує ту саму версію протоколу Codex app-server. +**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` +і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Не-Codex модель використовує PI:** це очікувана поведінка. Codex harness обробляє лише +**Не-Codex модель використовує PI:** це очікувана поведінка. Каркас Codex обробляє лише посилання на моделі `codex/*`. ## Пов’язане -- [Плагіни Agent Harness](/uk/plugins/sdk-agent-harness) +- [Плагіни каркаса агента](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index ec1a2fb47..1be6a291c 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,53 +1,60 @@ --- read_when: - - Ви змінюєте вбудований рантайм агента або реєстр harnessів + - Ви змінюєте вбудоване середовище виконання агента або реєстр harness агентів - Ви реєструєте harness агента з вбудованого або довіреного плагіна - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агентів +summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента title: Плагіни Agent Harness x-i18n: - generated_at: "2026-04-10T21:05:18Z" + generated_at: "2026-04-10T23:15:01Z" model: gpt-5.4 provider: openai - source_hash: 3abada0b89609c80edf3b66dfbd5951e812523c31d758643edb92e01f86e6dae + source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1 source_path: plugins/sdk-agent-harness.md workflow: 15 --- # Плагіни Agent Harness -**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. +**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу +агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований раннер. +Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт +досі є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний +вбудований виконавець. ## Коли використовувати harness -Реєструйте agent harness, коли сімейство моделей має власний нативний рантайм сесій і звичайний транспорт постачальника OpenClaw є хибною абстракцією. +Реєструйте agent harness, коли сімейство моделей має власне нативне середовище +виконання сесії, а звичайний транспорт постачальника OpenClaw є хибною абстракцією. Приклади: -- нативний сервер coding-agent, який керує потоками й компакцією -- локальний CLI або демон, який має транслювати нативні події плану/міркування/інструментів -- рантайм моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw +- нативний сервер coding-agent, який керує потоками та компакцією +- локальний CLI або демон, який має потоково передавати нативні події плану/міркувань/інструментів +- середовище виконання моделі, якому потрібен власний id відновлення на додачу до + транскрипту сесії OpenClaw -**Не** реєструйте harness лише для того, щоб додати новий LLM API. Для звичайних HTTP або WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте harness лише для додавання нового API LLM. Для звичайних HTTP- або +WebSocket-API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). -## Чим і далі керує ядро +## Що все ще належить core Перш ніж буде вибрано harness, OpenClaw уже визначив: -- постачальника й модель -- стан автентифікації рантайму -- рівень міркування й бюджет контексту -- транскрипт OpenClaw/файл сесії +- постачальника і модель +- стан автентифікації середовища виконання +- рівень thinking і бюджет контексту +- файл транскрипту/сесії OpenClaw - робочий простір, sandbox і політику інструментів -- колбеки відповіді каналу та колбеки потокової передачі -- політику резервного переходу між моделями й перемикання на живу модель +- зворотні виклики відповіді каналу та потокові зворотні виклики +- резервну модель і політику перемикання live-моделей -Такий поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає постачальників, не замінює доставку через канали й не перемикає моделі непомітно. +Цей розподіл є навмисним. Harness виконує підготовлену спробу; він не вибирає +постачальників, не замінює доставку через канал і не перемикає моделі непомітно. -## Зареєструвати harness +## Реєстрація harness **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -87,38 +94,61 @@ export default definePluginEntry({ OpenClaw вибирає harness після визначення постачальника/моделі: -1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований harness з таким id. -2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований harness PI. -3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness-и, чи підтримують вони визначеного постачальника/модель. -4. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо резервний перехід до PI не вимкнено. +1. `OPENCLAW_AGENT_RUNTIME=` примусово вказує зареєстрований harness із цим id. +2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вказує вбудований harness PI. +3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness, чи підтримують вони + визначеного постачальника/модель. +4. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо резервний варіант PI не вимкнено. -Помилки примусово вибраного harness плагіна відображаються як помилки виконання. У режимі `auto` OpenClaw може повернутися до PI, якщо вибраний harness плагіна зазнає збою до того, як хід створить побічні ефекти. Встановіть `OPENCLAW_AGENT_HARNESS_FALLBACK=none` або `embeddedHarness.fallback: "none"`, щоб зробити такий резервний перехід жорсткою помилкою. +Збої примусово вказаного harness плагіна відображаються як збої виконання. У режимі `auto` +OpenClaw може перейти на PI, якщо вибраний harness плагіна зазнає збою до того, +як хід спричинить побічні ефекти. Установіть `OPENCLAW_AGENT_HARNESS_FALLBACK=none` або +`embeddedHarness.fallback: "none"`, щоб зробити такий перехід жорсткою помилкою. -Вбудований плагін Codex реєструє `codex` як id свого harness. Для сумісності `codex-app-server` і `app-server` також указують на цей самий harness, коли ви вручну встановлюєте `OPENCLAW_AGENT_RUNTIME`. +Вбудований плагін Codex реєструє `codex` як свій id harness. Core розглядає його +як звичайний id harness плагіна; специфічні для Codex псевдоніми мають належати +плагіну або конфігурації оператора, а не спільному селектору середовища виконання. -## Поєднання постачальника й harness +## Зіставлення постачальника та harness -Більшість harness-ів також мають реєструвати постачальника. Постачальник робить посилання на моделі, статус автентифікації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім harness заявляє про цей постачальник у `supports(...)`. +Більшість harness також мають реєструвати постачальника. Постачальник робить +посилання на моделі, стан автентифікації, метадані моделей і вибір `/model` +видимими для решти OpenClaw. Потім harness заявляє цей постачальник у `supports(...)`. Вбудований плагін Codex дотримується цього шаблону: - id постачальника: `codex` -- посилання користувача на моделі: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, яку повертає сервер застосунку Codex +- посилання користувача на моделі: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, яку повертає + сервер застосунку Codex - id harness: `codex` -- автентифікація: синтетична доступність постачальника, оскільки harness Codex керує нативним входом/сесією Codex -- запит до app-server: OpenClaw надсилає до Codex лише id моделі й дозволяє harness-у взаємодіяти з нативним протоколом app-server +- автентифікація: синтетична доступність постачальника, оскільки harness Codex керує + нативним входом/сесією Codex +- запит до app-server: OpenClaw надсилає до Codex базовий id моделі й дозволяє + harness взаємодіяти з нативним протоколом app-server -Плагін Codex є доповненням. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI й продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI. +Плагін Codex є доповнювальним. Звичайні посилання `openai/gpt-*` залишаються +посиланнями постачальника OpenAI і продовжують використовувати звичайний шлях +постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, +виявлення моделей Codex, нативні потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app server Codex, не вимагаючи облікових даних постачальника OpenAI. -Налаштування оператором, приклади префіксів моделей і конфігурації лише для Codex дивіться в [Codex Harness](/uk/plugins/codex-harness). +Налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex див. у +[Codex Harness](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє initialize-handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє +ініціалізаційне рукостискання app-server і блокує старіші сервери або сервери без версії, щоб +OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. -## Вимкнення резервного переходу до PI +## Вимкнення резервного PI -Типово OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness-и плагінів можуть заявити підтримку пари постачальник/модель. Якщо жоден не підходить або якщо автоматично вибраний harness плагіна зазнає збою до створення виводу, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, +встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані +harness плагінів можуть заявляти пари постачальник/модель. Якщо жоден не підходить +або якщо автоматично вибраний harness плагіна зазнає збою до створення виводу, +OpenClaw переходить на PI. -Установіть `fallback: "none"`, якщо вам потрібно довести, що виконується лише рантайм harness плагіна. Це вимикає автоматичний резервний перехід до PI; це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли потрібно довести, що єдиним середовищем +виконання, яке використовується, є harness плагіна. Це вимикає автоматичний резервний перехід на PI; +це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. Для вбудованих запусків лише з Codex: @@ -136,7 +166,9 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявити підтримку відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть резервний перехід: +Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявляти +відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште +`runtime: "auto"` і вимкніть резервний перехід: ```json { @@ -151,7 +183,7 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -Перевизначення на рівні окремого агента використовують ту саму форму: +Перевизначення для окремого агента використовують ту саму форму: ```json { @@ -176,7 +208,9 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштований рантайм. Використайте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід до PI через середовище. +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через +змінну середовища. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -184,39 +218,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, коли запитаний harness не зареєстровано, не підтримує визначеного постачальника/модель або зазнає збою до створення побічних ефектів ходу. Це зроблено навмисно для середовищ лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях app-server Codex. +Із вимкненим резервним переходом сесія завершується помилкою на ранньому етапі, якщо запитаний harness не +зареєстровано, не підтримує визначеного постачальника/модель або зазнає збою до +створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і +для live-тестів, які мають довести, що шлях через app-server Codex справді використовується. -Цей параметр керує лише вбудованим agent harness. Він не вимикає маршрутизацію моделей, специфічну для постачальника, для зображень, відео, музики, TTS, PDF або інших типів. +Цей параметр керує лише вбудованим harness агента. Він не вимикає маршрутизацію +зображень, відео, музики, TTS, PDF або інших специфічних для постачальника моделей. -## Нативні сесії та дзеркалення транскрипту +## Нативні сесії та дзеркалювання транскрипту -Harness може зберігати нативний id сесії, id потоку або daemon-side токен відновлення. Явно пов’язуйте таку прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий користувачу вивід помічника/інструментів у транскрипт OpenClaw. +Harness може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. +Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте +дзеркалювати видимий користувачу вивід помічника/інструментів у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: - історії сесії, видимої в каналі -- пошуку та індексації транскрипту -- повернення до вбудованого harness PI на наступному ході -- узагальненої поведінки `/new`, `/reset` і видалення сесії +- пошуку та індексації транскриптів +- перемикання назад на вбудований harness PI у наступному ході +- загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваш harness зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли відповідну сесію OpenClaw буде скинуто. +Якщо ваш harness зберігає прив’язку sidecar, реалізуйте `reset(...)`, щоб OpenClaw міг +очищати її, коли пов’язану сесію OpenClaw скинуто. ## Результати інструментів і медіа -Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента через форму результату harness, а не надсилайте медіа в канал самостійно. +Core формує список інструментів OpenClaw і передає його в підготовлену спробу. +Коли harness виконує виклик динамічного інструмента, повертайте результат інструмента +назад через форму результату harness замість того, щоб самостійно надсилати медіа в канал. -Це дозволяє тексту, зображенням, відео, музиці, TTS, погодженням і результатам інструментів обміну повідомленнями проходити тим самим шляхом доставки, що й запуски на основі PI. +Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи інструментів обміну повідомленнями +на тому самому шляху доставки, що й у запусках на основі PI. ## Поточні обмеження -- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` для сумісності. -- Встановлення сторонніх harness-ів є експериментальним. Надавайте перевагу плагінам постачальників, доки вам не знадобиться нативний рантайм сесій. -- Перемикання harness-ів між ходами підтримується. Не перемикайте harness посеред ходу після того, як уже почалися нативні інструменти, погодження, текст помічника або надсилання повідомлень. +- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроби/результату все ще + містять назви `Pi` для сумісності. +- Встановлення сторонніх harness є експериментальним. Надавайте перевагу плагінам постачальників, + доки вам не знадобиться нативне середовище виконання сесії. +- Перемикання harness між ходами підтримується. Не перемикайте harness посеред + ходу після того, як уже почалися нативні інструменти, погодження, текст помічника або + надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Допоміжні засоби рантайму](/uk/plugins/sdk-runtime) +- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) - [Codex Harness](/uk/plugins/codex-harness) - [Постачальники моделей](/uk/concepts/model-providers)