From c8859210bf96bc0ff7adcc70aadd678fd8acd31d Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 01:03:07 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 525 +++++++++++++++--------------- docs/uk/tools/index.md | 146 ++++----- docs/uk/tools/music-generation.md | 167 +++++----- 3 files changed, 431 insertions(+), 407 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 84bfc4fdf..bed6e4c1a 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для багів моделей/провайдерів - - Налагодження поведінки gateway + агента + - Додавання регресій для багів моделі/провайдера + - Налагодження поведінки gateway і агента summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-06T00:49:34Z" + generated_at: "2026-04-06T01:03:06Z" model: gpt-5.4 provider: openai - source_hash: ef02b860d1a76c5da2bcd2479bb2a51223a30aa2c4a10a5dd3efa91225d41787 + source_hash: cfa174e565df5fdf957234b7909beaf1304aa026e731cc2c433ca7d931681b56 source_path: help/testing.md workflow: 15 --- @@ -20,80 +20,80 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває) +- Що покриває кожен набір (і чого він навмисно _не_ покриває) - Які команди запускати для типових сценаріїв (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем із моделями/провайдерами +- Як додавати регресії для реальних проблем моделей/провайдерів ## Швидкий старт У більшості випадків: -- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm test` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest (сучасна конфігурація projects): `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` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви торкаєтеся тестів або хочете більше впевненості: -- Перевірка покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): -- Live-набір (моделі + gateway-проби інструментів/зображень): `pnpm test:live` -- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Набір live (моделі + gateway tool/image probes): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один збійний кейс, краще звузити live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. -## Набори тестів (що і де запускається) +## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як такі, що мають «зростаючий реалізм» (і зростаючу нестабільність/вартість): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: вбудовані Vitest `projects` через `vitest.config.ts` -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` та дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Конфігурація: нативні Vitest `projects` через `vitest.config.ts` +- Файли: core/unit inventories у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` та дозволені `ui` node-тести, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process інтеграційні тести (gateway auth, routing, tooling, parsing, config) + - Внутрішньопроцесні integration-тести (gateway auth, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - Примітка про projects: - - `pnpm test`, `pnpm test:watch` і `pnpm test:changed` тепер усі використовують ту саму вбудовану кореневу конфігурацію Vitest `projects`. - - Прямі файлові фільтри маршрутизуються нативно через граф кореневого проєкту, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` працює без спеціальної обгортки. -- Примітка про вбудований runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime ущільнення, - зберігайте обидва рівні покриття. + - `pnpm test`, `pnpm test:watch` і `pnpm test:changed` тепер використовують однакову нативну кореневу конфігурацію Vitest `projects`. + - Прямі файлові фільтри нативно маршрутизуються через граф кореневого проєкту, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` працює без спеціальної обгортки. +- Примітка про вбудований раннер: + - Коли ви змінюєте входи виявлення message-tool або контекст runtime compaction, + зберігайте покриття на обох рівнях. - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте в здоровому стані інтеграційні набори вбудованого runner: + - Також підтримуйте здоровими integration-набори вбудованого раннера: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id та поведінка ущільнення все ще проходять + - Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих інтеграційних шляхів. + достатньою заміною цих integration-шляхів. - Примітка про pool: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований runner у кореневих projects, e2e та live-конфігураціях. - - Коренева UI-lane зберігає свій `jsdom` setup та optimizer, але тепер також працює на спільному неізольованому runner. - - `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` із конфігурації projects у кореневому `vitest.config.ts`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований раннер для кореневих projects, e2e та live конфігурацій. + - Коренева гілка UI зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному неізольованому раннері. + - `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` з конфігурації projects у кореневому `vitest.config.ts`. - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. - Примітка про швидку локальну ітерацію: - - `pnpm test:changed` запускає вбудовану конфігурацію projects з `--changed origin/main`. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму вбудовану конфігурацію projects, лише з вищим лімітом воркерів. - - Автомасштабування локальних воркерів тепер навмисно консервативніше та також зменшує навантаження, коли середнє навантаження хоста вже високе, тому кілька паралельних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски у changed-режимі лишалися коректними, коли змінюється тестова обв’язка. - - Конфігурація лишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну директорію кешу для прямого профілювання. + - `pnpm test:changed` запускає нативну конфігурацію projects з `--changed origin/main`. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму нативну конфігурацію projects, лише з вищим лімітом worker-ів. + - Автомасштабування локальних worker-ів тепер навмисно консервативне й також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітність про тривалість імпортів у Vitest та вивід розбивки імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими відносно `origin/main`. - - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для накладних витрат запуску та трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим файловим паралелізмом. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів і вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими відносно `origin/main`. + - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap раннера для unit-набору з вимкненим файловим паралелізмом. ### E2E (gateway smoke) @@ -102,35 +102,35 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 типово). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. -- Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (не більше 16). + - Використовує адаптивну кількість worker-ів (CI: до 2, локально: типово 1). + - Типово працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. +- Корисні overrides: + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker-ів (обмеження — 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing вузлів і складніші мережеві сценарії + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і складніший networking - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke бекенда OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи з remote-canonical semantics через sandbox fs bridge + - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного демона Docker - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестові gateway і sandbox -- Корисні перевизначення: + - Потрібен локальний CLI `openshell` і справний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox +- Корисні overrides: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) @@ -139,30 +139,30 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем auth та поведінки rate limit + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей tool-calling, проблем auth і поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Навмисно не стабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски підвантажують `~/.profile`, щоб підхопити відсутні API-ключі. -- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували вашу реальну домашню директорію. -- `pnpm test:live` тепер типово працює в тихішому режимі: він лишає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи bootstrap gateway/Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або окреме перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth матеріали у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежно від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте per-live override через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів видно як активні навіть коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway транслюються одразу під час live-запусків. - - Налаштуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдерів помітно активні навіть коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway відразу транслюються під час live-запусків. + - Налаштовуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який набір мені запускати? +## Який набір запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) - Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запустіть звужений `pnpm test:live` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android node @@ -170,110 +170,110 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Скрипт: `pnpm android:test:integration` - Мета: викликати **кожну команду, яку зараз рекламує** підключений Android node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлений/ручний setup (набір не встановлює/не запускає/не pair-ить app). - - Перевірка `node.invoke` gateway для вибраного Android node команда за командою. -- Обов’язковий попередній setup: - - Android app вже підключено та pair-ено з gateway. - - App утримується на передньому плані. - - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте перевірити успішно. -- Необов’язкові перевизначення цілі: + - Налаштування вручну як передумова (набір не встановлює/не запускає/не pair-ить app). + - Валідація `node.invoke` gateway по командах для вибраного Android node. +- Обов’язкове попереднє налаштування: + - Android app уже підключено й pair-ено з gateway. + - App має залишатися на передньому плані. + - Права/згоду на захоплення надано для можливостей, які ви очікуєте як успішні. +- Необов’язкові overrides цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні деталі setup Android: [Android App](/uk/platforms/android) +- Повні деталі налаштування Android: [Android App](/uk/platforms/android) ## Live: smoke моделей (ключі профілів) -Live-тести розділено на два шари, щоб можна було ізолювати збої: +Live-тести розділено на два рівні, щоб можна було ізолювати збої: -- «Пряма модель» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює для цієї моделі весь pipeline gateway+agent (sessions, history, tools, sandbox policy тощо). +- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). -### Шар 1: Пряме завершення моделі (без gateway) +### Рівень 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перерахувати виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) + - Перелічити виявлені моделі + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Запустити невелике completion для кожної моделі (і точкові регресії там, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` лишався зосередженим на gateway smoke +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity"` (allowlist через кому) - Звідки беруться ключі: - - Типово: store профілів і резервні значення env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише store профілів** + - Типово: зі сховища профілів і env fallback-ів + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламано / ключ невалідний» від «pipeline gateway agent зламано» - - Містить невеликі, ізольовані регресії (наприклад: відтворення reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: replay міркувань OpenAI Responses/Codex Responses + потоки tool-call) -### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Рівень 2: smoke gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі-з-ключами та перевіряти: - - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (read probe) + - Створити/оновити session `agent:dev:*` (override моделі для кожного запуску) + - Перебрати моделі з ключами й перевірити: + - «змістовну» відповідь (без tools) + - що працює реальний виклик інструмента (read probe) - необов’язкові додаткові probe інструментів (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probe (щоб можна було швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace й просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що регресійні шляхи OpenAI (лише tool-call → follow-up) і далі працюють +- Деталі probe (щоб можна було швидко пояснити збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` зчитати його назад. + - image probe: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір -- Як вибирати провайдерів (уникайте «усе з OpenRouter»): + - Типово: 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"` (або список через кому), щоб звузити набір +- Як вибирати провайдерів (уникати «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,openai,anthropic,zai,minimax"` (allowlist через кому) -- Проби інструментів і зображень у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на інструменти) - - image probe запускається, коли модель заявляє про підтримку image input +- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені: + - `read` probe + `exec+read` probe (навантаження на tools) + - image probe запускається, коли модель оголошує підтримку image input - Потік (на високому рівні): - - Тест генерує маленький 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: незначні помилки дозволені) + - Вбудований агент пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (толерантність до OCR: незначні помилки допускаються) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: ACP bind smoke (`/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: +- Мета: перевірити реальний потік conversation-bind ACP із live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати synthetic conversation message-channel на місці - - надіслати звичайне follow-up у тій самій conversation - - перевірити, що follow-up потрапляє до transcript прив’язаної ACP session + - прив’язати synthetic розмову message-channel на місці + - надіслати звичайний follow-up у цій самій розмові + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agent: `claude` - - Synthetic channel: контекст conversation у стилі Slack DM + - ACP-агент: `claude` + - Synthetic channel: контекст розмови в стилі Slack DM - ACP backend: `acpx` -- Перевизначення: +- Overrides: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця lane використовує surface `chat.send` gateway з synthetic полями originating-route лише для адміністраторів, щоб тести могли додавати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів вибраного ACP harness agent із plugin `acpx`. + - Ця доріжка використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли приєднати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -292,12 +292,12 @@ pnpm test:docker:live-acp-bind Примітки щодо Docker: - Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Він підвантажує `~/.profile`, переносить відповідний CLI auth-матеріал у контейнер, встановлює `acpx` у записуваний npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`), якщо його бракує. -- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підвантаженого profile доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, додає відповідні матеріали auth CLI в контейнер, установлює `acpx` у записуваний npm prefix, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`), якщо його немає. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env vars провайдера з використаного profile доступними для дочірнього harness CLI. ### Рекомендовані live-рецепти -Вузькі явні allowlist-и — найшвидші й найменш нестабільні: +Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -305,7 +305,7 @@ pnpm test:docker:live-acp-bind - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів для кількох провайдерів: +- Tool calling через кілька провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -315,17 +315,17 @@ pnpm test:docker:live-acp-bind Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента у стилі Cloud Code Assist). +- `google-antigravity/...` використовує міст Antigravity OAuth (agent endpoint у стилі Cloud Code Assist). ## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (live є opt-in), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний smoke-набір (tool calling + image) Це запуск «типових моделей», який ми очікуємо підтримувати в робочому стані: -- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -333,12 +333,12 @@ pnpm test:docker:live-acp-bind - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустити gateway smoke з інструментами + зображенням: +Запустити gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть принаймні одну модель для кожної сім’ї провайдерів: +Виберіть принаймні одну модель з кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -349,77 +349,77 @@ pnpm test:docker:live-acp-bind Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яка у вас увімкнена) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від API-режиму) +- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (attachment → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateway +### Aggregators / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), а також будь-який сумісний з OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic 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` (саме це означають «ключі профілів» у live-тестах) - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Legacy state dir: `~/.openclaw/credentials/` (копіюється у staged live home, якщо присутня, але не є основним store ключів профілю) -- Локальні live-запуски типово копіюють активний config, файли `auth-profiles.json` для кожного агента, legacy `credentials/` і підтримувані зовнішні CLI auth-директорії в тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються з цього staged config, щоб probe не працювали у вашому реальному workspace хоста. +- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але це не основне сховище ключів профілів) +- Локальні live-запуски типово копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні CLI auth-каталоги в тимчасовий test home; overrides шляху `agents.*.workspace` / `agentDir` у цьому staged config прибираються, щоб probes не торкалися вашого реального host workspace. Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрипція аудіо) +## Live Deepgram (аудіотранскрипція) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live BytePlus coding plan - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live ComfyUI workflow media - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у поданні comfy workflow, polling, завантаженнях або реєстрації plugin + - Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації plugin -## Live генерації зображень +## Live генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Обсяг: - - Перераховує всі зареєстровані plugin провайдерів генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед виконанням probe - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Перелічує кожен зареєстрований plugin провайдера генерації зображень + - Завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не перекривали реальні shell credentials - Пропускає провайдерів без придатного auth/profile/model - - Пропускає стандартні варіанти генерації зображень через спільну runtime capability: + - Запускає стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери в покритті: +- Поточні вбудовані провайдери, що покриваються: - `openai` - `google` - Необов’язкове звуження: @@ -427,185 +427,198 @@ 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-only overrides + +## Live генерація музики + +- Тест: `extensions/music-generation-providers.live.test.ts` +- Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` +- Обсяг: + - Перевіряє спільний вбудований шлях провайдера генерації музики + - Наразі покриває Google і MiniMax + - Завантажує env vars провайдера з вашого login shell (`~/.profile`) перед probe + - Пропускає провайдерів без придатного auth/profile/model +- Необов’язкове звуження: + - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` + - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці Docker-ранери поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують вашу локальну config-директорію та workspace (і підвантажують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери типово використовують менший smoke-ліміт, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` типово встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (і використовуючи `~/.profile`, якщо змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker-ранери live типово використовують менший smoke-ліміт, щоб повний Docker-sweep залишався практичним: + `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `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`, а потім повторно використовує його для двох Docker-lane live. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначте ці env vars, коли + вам навмисно потрібне більший вичерпний scan. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-доріжок live. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня. -Ранери Docker для live-моделей також bind-mount-ять лише потрібні auth-home CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени без змін у host auth store: +Ранери Docker для live-моделей також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без змін у host auth store: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-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, повне scaffold-ування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Gateway networking (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude smoke notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Ранери Docker для live-моделей також bind-mount-ять поточний checkout у режимі лише читання й -розміщують його у тимчасовому workdir усередині контейнера. Це робить runtime- -образ компактним, але все одно запускає Vitest точно на ваших локальних source/config. -Крок staging пропускає великі локальні кеші та артефакти збірки app, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні директорії `.build` app або -вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, прив’язаних до конкретної машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали -реальні воркери каналів Telegram/Discord/etc. усередині контейнера. +Ранери Docker для live-моделей також bind-mount-ять поточний checkout лише для читання і +стейджать його у тимчасовий workdir усередині контейнера. Це зберігає runtime +образ компактним, але водночас дає запускати Vitest точно на вашому локальному source/config. +Крок staging пропускає великі локальні кеші та build-артефакти app, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали +реальні воркери каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway- -live покриття з цієї Docker-lane. -`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway +live із цієї Docker-доріжки. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає контейнер gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, -запускає контейнер Open WebUI із зафіксованою версією проти цього gateway, входить -через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через proxy Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, бо Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власний cold-start setup. -Ця lane очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Docker-запусках. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний chat request через proxy `/api/chat/completions` в Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути +образ Open WebUI, а Open WebUI може потребувати завершити власне cold-start налаштування. +Ця доріжка очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його у Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він піднімає seeded Gateway- -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих conversation, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію outbound send та повідомлення про channel + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка повідомлень -аналізує сирі stdio MCP frames напряму, тож smoke перевіряє те, що -міст фактично випромінює, а не лише те, що випадково показує певний client SDK. +реального акаунта Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway, +стартує другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень, +поведінку live event queue, маршрутизацію outbound send, а також сповіщення про канал + +дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +напряму аналізує сирі stdio MCP frames, тож smoke перевіряє те, що +міст справді випромінює, а не лише те, що випадково показує певний client SDK. Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Залишайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації 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 -- Зовнішні CLI auth-директорії/файли під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - - Типові директорії: `.minimax` +- `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-каталоги/файли в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів + - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні директорії/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Для ручного перевизначення використовуйте `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі store профілів (а не з env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...` щоб перевизначити зафіксований тег образу Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, який використовується для smoke Open WebUI +- `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків усередині сторінок: `pnpm docs:check-links:anchors`. +Запускайте перевірки docs після редагування документації: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли потрібні також перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів 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 loop): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard (WS `wizard.start`/`wizard.next`, записує config + примусове auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агентів (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Імітований виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, що перевіряють session wiring і впливи config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний gateway + agent loop (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють wiring сесій і вплив config (`src/gateway/gateway.test.ts`). Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): - **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії session та межі sandbox. +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? +- **Контракти робочого процесу:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають передусім залишатися детермінованими: +Майбутні evals мають передусім залишатися детермінованими: -- Scenario runner із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і wiring session. -- Невеликий набір сценаріїв, зосереджених на skills (використати чи уникнути, gating, prompt injection). -- Необов’язкові live eval-и (opt-in, під контролем env) лише після того, як буде готовий безпечний для CI набір. +- Раннер сценаріїв, що використовує mock-провайдери для перевірки викликів tools + порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live evals (opt-in, env-gated) — лише після того, як буде готовий безпечний для CI набір. ## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму інтерфейсному контракту. Вони ітерують усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-lane `pnpm test` навмисно -пропускає ці спільні файли seam і smoke; запускайте контрактні команди окремо, +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типова unit-доріжка `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо, коли торкаєтеся спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти channels: `pnpm test:contracts:channels` -- Лише контракти providers: `pnpm test:contracts:plugins` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Контракти channels +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра setup -- **session-binding** - Поведінка прив’язки session +- **setup** - Контракт майстра налаштування +- **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Дотримання group policy +- **threading** - Обробка thread ID +- **directory** - API каталогу/реєстру +- **group-policy** - Застосування групових політик -### Контракти статусу providers +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Проби статусу channel +- **status** - Probe-и статусу channel - **registry** - Форма реєстру plugin -### Контракти providers +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth-choice** - Вибір/selection auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin - **runtime** - Runtime provider - **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер setup +- **wizard** - Майстер налаштування ### Коли запускати -- Після змін у plugin-sdk exports або subpath +- Після зміни exports або subpath-ів plugin-sdk - Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після рефакторингу реєстрації plugin або discovery Контрактні тести запускаються в CI й не потребують реальних API-ключів. -## Додавання регресій (настанови) +## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або зафіксуйте точну трансформацію форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Намагайтеся цілися в найменший шар, який виявляє баг: - - баг перетворення/відтворення запиту провайдера → тест direct models - - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Запобіжник обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не могли бути тихо пропущені. +- Якщо можливо, додавайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) +- Якщо це за своєю природою лише live-випадок (rate limits, політики auth), тримайте live-тест вузьким і opt-in через env vars +- Намагайтеся націлюватися на найменший рівень, який ловить баг: + - баг конвертації/replay запиту провайдера → тест direct models + - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Захисна умова обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній sampled target для кожного класу SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md index 19487f55e..4ab24a53c 100644 --- a/docs/uk/tools/index.md +++ b/docs/uk/tools/index.md @@ -2,25 +2,25 @@ read_when: - Ви хочете зрозуміти, які інструменти надає OpenClaw - Вам потрібно налаштувати, дозволити або заборонити інструменти - - 'Ви вирішуєте, що обрати: вбудовані інструменти, Skills чи plugins' -summary: 'Огляд інструментів і plugins OpenClaw: що може агент і як його розширювати' -title: Інструменти і Plugins + - Ви обираєте між вбудованими інструментами, Skills і плагінами +summary: 'Огляд інструментів і плагінів OpenClaw: що агент може робити та як його розширювати' +title: Інструменти та плагіни x-i18n: - generated_at: "2026-04-06T00:53:01Z" + generated_at: "2026-04-06T01:01:09Z" model: gpt-5.4 provider: openai - source_hash: c09e6ba0bba59be93eec676f119ab81b51f08536744f5d91f340734a4ce531c5 + source_hash: ce14e03c4b090dd183db86c509c248e21e5e882ae0900676166429fa33a940b6 source_path: tools/index.md workflow: 15 --- -# Інструменти і Plugins +# Інструменти та плагіни Усе, що агент робить окрім генерування тексту, відбувається через **інструменти**. -Інструменти — це спосіб, яким агент читає файли, виконує команди, переглядає вебсторінки, надсилає +Саме через інструменти агент читає файли, виконує команди, переглядає вебсторінки, надсилає повідомлення та взаємодіє з пристроями. -## Інструменти, Skills і plugins +## Інструменти, Skills і плагіни OpenClaw має три шари, які працюють разом: @@ -28,100 +28,100 @@ OpenClaw має три шари, які працюють разом: Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`, `web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а - plugins можуть реєструвати додаткові. + плагіни можуть реєструвати додаткові. Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі. - - Skill — це markdown-файл (`SKILL.md`), який вбудовується в системний prompt. + + Skill — це markdown-файл (`SKILL.md`), що додається до системного prompt. Skills надають агенту контекст, обмеження та покрокові вказівки для - ефективного використання інструментів. Skills зберігаються у вашому workspace, у спільних теках - або постачаються всередині plugins. + ефективного використання інструментів. Skills розміщуються у вашому робочому просторі, у спільних папках + або постачаються всередині плагінів. - [Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) + [Довідник зі Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) - - Plugin — це пакет, який може реєструвати будь-яку комбінацію можливостей: - канали, провайдери моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, + + Плагін — це пакет, який може реєструвати будь-яку комбінацію можливостей: + канали, постачальників моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео, - отримання вебсторінок, вебпошук тощо. Деякі plugins є **core** (постачаються з - OpenClaw), інші — **external** (опубліковані спільнотою в npm). + web fetch, web search тощо. Деякі плагіни є **core** (постачаються разом з + OpenClaw), інші — **external** (публікуються спільнотою на npm). - [Встановлення і налаштування plugins](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) + [Встановлення та налаштування плагінів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) ## Вбудовані інструменти -Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких plugins: +Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких плагінів: -| Інструмент | Що він робить | Сторінка | -| ------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------- | -| `exec` / `process` | Виконує shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec) | -| `code_execution` | Виконує ізольований віддалений аналіз Python | [Code Execution](/uk/tools/code-execution) | -| `browser` | Керує браузером Chromium (перехід, клік, знімок екрана) | [Browser](/uk/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Web](/uk/tools/web) | -| `read` / `write` / `edit` | Ввід/вивід файлів у workspace | | -| `apply_patch` | Патчі файлів із кількома фрагментами | [Apply Patch](/uk/tools/apply-patch) | -| `message` | Надсилає повідомлення в усі канали | [Agent Send](/uk/tools/agent-send) | -| `canvas` | Керує node Canvas (present, eval, snapshot) | | -| `nodes` | Виявляє та вибирає спарені пристрої | | -| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює gateway | | -| `image` / `image_generate` | Аналізує або генерує зображення | [Image Generation](/uk/tools/image-generation) | -| `music_generate` | Генерує музичні треки | [Music Generation](/uk/tools/music-generation) | -| `video_generate` | Генерує відео | [Video Generation](/uk/tools/video-generation) | -| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація субагентів | [Sub-agents](/uk/tools/subagents) | -| `session_status` | Полегшене читання у стилі `/status` і перевизначення моделі для сесії | [Session Tools](/uk/concepts/session-tool) | +| Інструмент | Що він робить | Сторінка | +| ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------- | +| `exec` / `process` | Виконує команди оболонки, керує фоновими процесами | [Exec](/uk/tools/exec) | +| `code_execution` | Виконує ізольований віддалений аналіз Python | [Code Execution](/uk/tools/code-execution) | +| `browser` | Керує браузером Chromium (навігація, натискання, знімки екрана) | [Browser](/uk/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web) | +| `read` / `write` / `edit` | Ввід/вивід файлів у робочому просторі | | +| `apply_patch` | Багатофрагментні патчі файлів | [Apply Patch](/uk/tools/apply-patch) | +| `message` | Надсилає повідомлення через усі канали | [Надсилання агентом](/uk/tools/agent-send) | +| `canvas` | Керує node Canvas (present, eval, snapshot) | | +| `nodes` | Виявляє та адресує спарені пристрої | | +| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює gateway | | +| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | +| `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) | +| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | +| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) | +| `session_status` | Полегшене зчитування у стилі `/status` і перевизначення моделі для сесії | [Інструменти сесії](/uk/concepts/session-tool) | -Для роботи із зображеннями використовуйте `image` для аналізу, а `image_generate` — для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого нестандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого неосновного постачальника зображень, спочатку налаштуйте автентифікацію/API-ключ цього постачальника. -Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого нестандартного музичного провайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого неосновного постачальника музики, спочатку налаштуйте автентифікацію/API-ключ цього постачальника. -Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нестандартного відеопровайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого неосновного постачальника відео, спочатку налаштуйте автентифікацію/API-ключ цього постачальника. -Для генерації аудіо на основі workflow використовуйте `music_generate`, коли plugin, наприклад -ComfyUI, реєструє його. Це окремо від `tts`, який відповідає за перетворення тексту на мовлення. +Для аудіогенерації на основі робочих процесів використовуйте `music_generate`, коли плагін на кшталт +ComfyUI реєструє його. Це окремо від `tts`, який є перетворенням тексту на мовлення. -`session_status` — це полегшений інструмент статусу/читання в групі sessions. -Він відповідає на запитання у стилі `/status` про поточну сесію і може -за потреби встановлювати перевизначення моделі для окремої сесії; `model=default` очищає це -перевизначення. Як і `/status`, він може заповнювати відсутні лічильники токенів/кешу та -мітку активної runtime-моделі з найновішого запису використання в транскрипті. +`session_status` — це полегшений інструмент статусу/зчитування в групі sessions. +Він відповідає на запитання у стилі `/status` про поточну сесію та може +за потреби встановлювати перевизначення моделі для окремої сесії; `model=default` скидає це +перевизначення. Як і `/status`, він може заповнювати пропущені лічильники токенів/кешу та +мітку активної моделі середовища виконання з останнього запису використання у транскрипті. -`gateway` — це runtime-інструмент лише для власника, призначений для операцій gateway: +`gateway` — це інструмент середовища виконання лише для власника для операцій gateway: -- `config.schema.lookup` для однієї підгілки конфігурації в межах шляху перед редагуванням +- `config.schema.lookup` для одного піддерева конфігурації в межах шляху перед редагуванням - `config.get` для поточного знімка конфігурації + хешу - `config.patch` для часткових оновлень конфігурації з перезапуском - `config.apply` лише для повної заміни конфігурації - `update.run` для явного самооновлення + перезапуску -Для часткових змін віддавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте -`config.apply` лише тоді, коли ви свідомо замінюєте всю конфігурацію. +Для часткових змін надавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте +`config.apply` лише тоді, коли ви навмисно замінюєте всю конфігурацію. Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec. -### Інструменти, надані plugins +### Інструменти, що надаються плагінами -Plugins можуть реєструвати додаткові інструменти. Деякі приклади: +Плагіни можуть реєструвати додаткові інструменти. Деякі приклади: -- [Lobster](/uk/tools/lobster) — типізоване workflow-runtime із відновлюваними схваленнями +- [Lobster](/uk/tools/lobster) — типізоване середовище виконання робочих процесів із відновлюваними погодженнями - [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу -- [Music Generation](/uk/tools/music-generation) — поверхні інструмента `music_generate`, надані plugin +- [Music Generation](/uk/tools/music-generation) — спільний інструмент `music_generate` плюс варіанти робочих процесів, надані плагінами - [Diffs](/uk/tools/diffs) — переглядач і рендерер diff -- [OpenProse](/uk/prose) — оркестрація workflow у стилі markdown-first +- [OpenProse](/uk/prose) — оркестрація робочих процесів із пріоритетом на markdown ## Налаштування інструментів ### Списки дозволів і заборон -Керуйте тим, які інструменти може викликати агент, через `tools.allow` / `tools.deny` у +Керуйте тим, які інструменти агент може викликати, за допомогою `tools.allow` / `tools.deny` у конфігурації. Заборона завжди має пріоритет над дозволом. ```json5 @@ -135,25 +135,25 @@ Plugins можуть реєструвати додаткові інструме ### Профілі інструментів -`tools.profile` задає базовий список дозволів перед застосуванням `allow`/`deny`. +`tools.profile` встановлює базовий список дозволів перед застосуванням `allow`/`deny`. Перевизначення для окремого агента: `agents.list[].tools.profile`. | Профіль | Що він включає | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `full` | Без обмежень (так само, як якщо не задано) | +| `full` | Без обмежень (так само, як якщо не встановлено) | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | -| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `minimal` | Лише `session_status` | ### Групи інструментів -Використовуйте скорочення `group:*` у списках allow/deny: +Використовуйте скорочення `group:*` у списках дозволів/заборон: | Група | Інструменти | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | | `group:fs` | read, write, edit, apply_patch | -| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | +| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | | `group:memory` | memory_search, memory_get | | `group:web` | web_search, x_search, web_fetch | | `group:ui` | browser, canvas | @@ -162,21 +162,21 @@ Plugins можуть реєструвати додаткові інструме | `group:nodes` | nodes | | `group:agents` | agents_list | | `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Усі вбудовані інструменти OpenClaw (без інструментів plugin) | +| `group:openclaw` | Усі вбудовані інструменти OpenClaw (без інструментів плагінів) | `sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для пригадування. Воно видаляє -теги thinking, каркас ``, XML-корисні навантаження викликів інструментів у звичайному тексті +теги thinking, каркас ``, XML-пейлоади викликів інструментів у відкритому тексті (включно з `...`, `...`, `...`, -`...` і усіченими блоками викликів інструментів), -понижений каркас викликів інструментів, витеклі ASCII/повноширинні токени керування моделлю -та некоректний XML викликів інструментів MiniMax із тексту помічника, а потім застосовує -редагування/усічення та, за потреби, заповнювачі для надто великих рядків, замість того щоб діяти -як сирий дамп транскрипту. +`...` і обрізаними блоками викликів інструментів), +понижений каркас викликів інструментів, витеклі ASCII/повноширинні токени керування +моделлю та некоректний XML викликів інструментів MiniMax з тексту асистента, а потім застосовує +редагування/обрізання та, за потреби, заповнювачі для надто великих рядків замість того, щоб діяти +як необроблений дамп транскрипту. -### Обмеження для конкретних провайдерів +### Обмеження для конкретних постачальників -Використовуйте `tools.byProvider`, щоб обмежувати інструменти для конкретних провайдерів без +Використовуйте `tools.byProvider`, щоб обмежувати інструменти для конкретних постачальників без зміни глобальних значень за замовчуванням: ```json5 diff --git a/docs/uk/tools/music-generation.md b/docs/uk/tools/music-generation.md index a37ac2d75..06297e61e 100644 --- a/docs/uk/tools/music-generation.md +++ b/docs/uk/tools/music-generation.md @@ -1,45 +1,41 @@ --- read_when: - Генерація музики або аудіо через агента - - Налаштування провайдерів і моделей генерації музики + - Налаштування провайдерів і моделей для генерації музики - Розуміння параметрів інструмента music_generate -summary: Генеруйте музику за допомогою спільних провайдерів або робочих процесів, наданих плагінами +summary: Створюйте музику через спільні провайдери або робочі процеси, надані плагінами title: Генерація музики x-i18n: - generated_at: "2026-04-06T00:52:57Z" + generated_at: "2026-04-06T01:01:03Z" model: gpt-5.4 provider: openai - source_hash: 7c4fa4b98627be77de47a8c53f686d9459ccc9ecf9064bb8459f94433afad5aa + source_hash: 10a310920a34a6d2aa90b82703b00dbd9944ec349ada948c3fdb12e9d45246a0 source_path: tools/music-generation.md workflow: 15 --- # Генерація музики -Інструмент `music_generate` дає змогу агенту створювати музику або аудіо за допомогою: +Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через: -- спільної можливості генерації музики з налаштованими провайдерами, такими як Google і MiniMax -- поверхонь інструментів, наданих плагінами, таких як граф ComfyUI, налаштований через workflow +- спільну можливість генерації музики з налаштованими провайдерами, такими як Google і MiniMax +- поверхні інструментів, надані плагінами, наприклад граф ComfyUI, налаштований через workflow -Для сеансів агента, що використовують спільних провайдерів, OpenClaw запускає генерацію музики як -фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли -трек готовий, щоб агент міг опублікувати готове аудіо назад у -початковий канал. +Для спільних агентських сесій, що працюють через провайдерів, OpenClaw запускає генерацію музики як фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента, коли трек готовий, щоб агент міг надіслати готове аудіо назад у початковий канал. -Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` в інструментах вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API key провайдера. +Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ провайдера. -Реалізації `music_generate`, надані плагінами, можуть мати інші параметри або поведінку під час виконання. Описаний нижче асинхронний потік завдань/стану застосовується до вбудованого шляху зі спільним провайдером. +Реалізації `music_generate`, надані плагінами, можуть мати інші параметри або іншу поведінку під час виконання. Наведений нижче асинхронний потік завдань/статусу застосовується до вбудованого спільного шляху на основі провайдерів. ## Швидкий старт -### Генерація через спільного провайдера +### Генерація через спільних провайдерів -1. Задайте API key принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або - `MINIMAX_API_KEY`. +1. Установіть API-ключ принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або `MINIMAX_API_KEY`. 2. За потреби задайте бажану модель: ```json5 @@ -54,22 +50,27 @@ x-i18n: } ``` -3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку - крізь неонове місто."_ +3. Попросіть агента: _"Згенеруй життєрадісний synthpop-трек про нічну поїздку неоновим містом."_ -Агент автоматично викликає `music_generate`. Додавання до allowlist інструментів не потрібне. +Агент автоматично викликає `music_generate`. Додавати інструмент до списку дозволених не потрібно. -Для прямих синхронних контекстів без запуску агента на основі сеансу вбудований -інструмент усе одно переходить до вбудованої генерації та повертає фінальний шлях до медіафайлу в -результаті інструмента. +Для прямих синхронних контекстів без запуску агента з прив’язкою до сесії вбудований інструмент усе одно переходить до вбудованої генерації та повертає фінальний шлях до медіафайлу в результаті інструмента. -### Генерація через плагін на основі workflow +Приклади запитів: -Вбудований плагін `comfy` також може надавати `music_generate` за допомогою -графа ComfyUI, налаштованого через workflow. +```text +Згенеруй кінематографічний фортепіанний трек із м’якими струнними й без вокалу. +``` -1. Налаштуйте `models.providers.comfy.music` із JSON workflow та - вузлами prompt/output. +```text +Згенеруй енергійний chiptune-луп про запуск ракети на світанку. +``` + +### Генерація через workflow у плагіні + +Комплектний плагін `comfy` також може надавати `music_generate` за допомогою графа ComfyUI, налаштованого через workflow. + +1. Налаштуйте `models.providers.comfy.music` за допомогою JSON workflow та вузлів prompt/output. 2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. 3. Попросіть агента створити музику або викличте інструмент безпосередньо. @@ -79,53 +80,63 @@ x-i18n: /tool music_generate prompt="Warm ambient synth loop with soft tape texture" ``` -## Підтримка спільних вбудованих провайдерів +## Підтримка спільних комплектних провайдерів -| Провайдер | Типова модель | Вхідні референси | Підтримувані елементи керування | API key | -| --------- | --------------------- | ---------------- | ------------------------------------------------------ | ---------------------------------- | -| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | +| Провайдер | Модель за замовчуванням | Вхідні посилання | Підтримувані елементи керування | API-ключ | +| --------- | ----------------------- | ---------------- | ------------------------------------------------------ | ---------------------------------- | +| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | ## Підтримка, надана плагінами -| Провайдер | Модель | Примітки | -| --------- | ---------- | ------------------------------- | +| Провайдер | Модель | Примітки | +| --------- | ---------- | -------------------------------- | | ComfyUI | `workflow` | Музика або аудіо, визначені workflow | -Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі -під час виконання: +Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери й моделі під час виконання: ```text /tool music_generate action=list ``` +Використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до сесії: + +```text +/tool music_generate action=status +``` + +Приклад прямої генерації: + +```text +/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true +``` + ## Параметри вбудованого інструмента -| Параметр | Тип | Опис | -| ----------------- | -------- | ------------------------------------------------------------------------------------------------- | -| `prompt` | string | Prompt для генерації музики (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сеансу або `"list"` для перегляду провайдерів | -| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | -| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явний вхід тексту | -| `instrumental` | boolean | Запитати вивід лише інструменталу, якщо провайдер це підтримує | -| `image` | string | Шлях або URL одного референсного зображення | -| `images` | string[] | Кілька референсних зображень (до 10) | -| `durationSeconds` | number | Цільова тривалість у секундах, якщо провайдер підтримує підказки тривалості | -| `format` | string | Підказка формату виводу (`mp3` або `wav`), якщо провайдер це підтримує | -| `filename` | string | Підказка імені вихідного файлу | +| Параметр | Тип | Опис | +| ---------------- | -------- | ------------------------------------------------------------------------------------------------- | +| `prompt` | string | Запит для генерації музики (обов’язковий для `action: "generate"`) | +| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії або `"list"` для перегляду провайдерів | +| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | +| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне введення лірики | +| `instrumental` | boolean | Запитати інструментальний результат без вокалу, якщо провайдер це підтримує | +| `image` | string | Шлях або URL одного зображення-посилання | +| `images` | string[] | Кілька зображень-посилань (до 10) | +| `durationSeconds`| number | Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості | +| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо провайдер це підтримує | +| `filename` | string | Підказка щодо імені вихідного файлу | -Не всі провайдери або плагіни підтримують усі параметри. Спільний вбудований інструмент -перевіряє обмеження можливостей провайдера перед надсиланням запиту. +Не всі провайдери або плагіни підтримують усі параметри. Спільний вбудований інструмент перевіряє обмеження можливостей провайдера перед надсиланням запиту. -## Асинхронна поведінка для шляху зі спільним провайдером +## Асинхронна поведінка для спільного шляху на основі провайдерів -- Запуски агента на основі сеансу: `music_generate` створює фонове завдання, одразу повертає відповідь про старт/завдання та публікує готовий трек пізніше в подальшому повідомленні агента. -- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тому самому сеансі повертають стан завдання замість запуску нової генерації. -- Перевірка стану: використовуйте `action: "status"`, щоб переглянути активне завдання музики, пов’язане з поточним сеансом, не запускаючи нове. -- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати стани queued, running і завершальні стани генерації. -- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у той самий сеанс, щоб модель могла сама написати подальше повідомлення для користувача. -- Підказка для prompt: наступні користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку часу виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` повторно бездумно. -- Резервний варіант без сеансу: прямі/локальні контексти без реального сеансу агента все одно виконуються вбудовано та повертають фінальний аудіорезультат у тому самому ході. +- Запуски агента, прив’язані до сесії: `music_generate` створює фонове завдання, одразу повертає відповідь про запуск/завдання, а готовий трек надсилає пізніше в наступному повідомленні агента. +- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають статус завдання замість запуску нової генерації. +- Перегляд статусу: використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до сесії, не запускаючи нове. +- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати стани queued, running і terminal для генерації. +- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати користувацьке повідомлення з результатом. +- Підказка для запиту: у наступних користувацьких/ручних кроках у тій самій сесії з’являється невелика підказка під час виконання, якщо завдання генерації музики вже виконується, щоб модель не викликала `music_generate` повторно без потреби. +- Резервний режим без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються вбудовано й повертають фінальний аудіорезультат у тому самому кроці. ## Конфігурація @@ -144,53 +155,53 @@ x-i18n: } ``` -### Порядок вибору провайдера +### Порядок вибору провайдерів -Під час генерації музики OpenClaw пробує провайдери в такому порядку: +Під час генерації музики OpenClaw пробує провайдерів у такому порядку: 1. параметр `model` з виклику інструмента, якщо агент його вказує 2. `musicGenerationModel.primary` з конфігурації -3. `musicGenerationModel.fallbacks` за порядком -4. Автовизначення лише за типовими варіантами провайдерів з автентифікацією: +3. `musicGenerationModel.fallbacks` у заданому порядку +4. Автовизначення лише з використанням типових значень провайдерів, підкріплених автентифікацією: - спочатку поточний типовий провайдер - - далі решта зареєстрованих провайдерів генерації музики в порядку ID провайдера + - решта зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів -Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, -помилка містить подробиці кожної спроби. +Якщо провайдер завершується помилкою, автоматично використовується наступний кандидат. Якщо помиляються всі, помилка містить деталі кожної спроби. ## Примітки щодо провайдерів -- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує - prompt, необов’язковий текст пісні та необов’язкові референсні зображення. -- MiniMax використовує пакетну кінцеву точку `music_generation`. Поточний вбудований потік - підтримує prompt, необов’язковий текст пісні, режим інструменталу, керування тривалістю та - вивід mp3. -- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та - зіставлення вузлів для полів prompt/output. +- Google використовує пакетну генерацію Lyria 3. Поточний комплектний потік підтримує prompt, необов’язковий текст лірики та необов’язкові зображення-посилання. +- MiniMax використовує пакетний endpoint `music_generation`. Поточний комплектний потік підтримує prompt, необов’язкову лірику, інструментальний режим, керування тривалістю та вивід у mp3. +- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та зіставлення вузлів для полів prompt/output. + +## Як вибрати правильний шлях + +- Використовуйте спільний шлях через провайдерів, якщо вам потрібні вибір моделі, перемикання між провайдерами при збоях і вбудований асинхронний потік завдань/статусу. +- Використовуйте шлях через плагін, наприклад ComfyUI, якщо вам потрібен власний граф workflow або провайдер, який не є частиною спільної комплектної можливості генерації музики. +- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте спільну поведінку провайдерів, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). ## Live-тести -Добровільне live-покриття для спільних вбудованих провайдерів: +Добровільне live-покриття для спільних комплектних провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts ``` -Добровільне live-покриття для вбудованого шляху музики ComfyUI: +Добровільне live-покриття для комплектного музичного шляху ComfyUI: ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Файл live-тестів Comfy також охоплює робочі процеси comfy для зображень і відео, коли ці -розділи налаштовані. +Файл live для Comfy також охоплює workflow для зображень і відео comfy, коли ці розділи налаштовані. ## Пов’язане - [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate` -- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - конфігурація `musicGenerationModel` +- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) - конфігурація `musicGenerationModel` - [ComfyUI](/uk/providers/comfy) - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax) -- [Моделі](/uk/concepts/models) - конфігурація моделей і резервне перемикання +- [Моделі](/uk/concepts/models) - конфігурація моделей і перемикання при збоях - [Огляд інструментів](/uk/tools)