From 77fe077025c710836f802420700a46ad9cfc2a9d Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 20:34:59 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing-live.md | 340 +++++++-------- docs/uk/plugins/building-plugins.md | 227 +++++----- docs/uk/plugins/manifest.md | 602 ++++++++++++++------------- docs/uk/plugins/sdk-agent-harness.md | 291 +++++++------ docs/uk/plugins/sdk-migration.md | 542 ++++++++++++------------ docs/uk/plugins/sdk-overview.md | 339 +++++++-------- docs/uk/providers/comfy.md | 268 ++++++------ docs/uk/tools/music-generation.md | 206 ++++----- 8 files changed, 1419 insertions(+), 1396 deletions(-) diff --git a/docs/uk/help/testing-live.md b/docs/uk/help/testing-live.md index f53fa33d7..299bb2d34 100644 --- a/docs/uk/help/testing-live.md +++ b/docs/uk/help/testing-live.md @@ -1,109 +1,109 @@ --- read_when: - - Запуск живих smoke-тестів для матриці моделей / бекенду CLI / ACP / медіапровайдера + - Запуск smoke-тестів для живої матриці моделей / бекенду CLI / ACP / медіапровайдерів - Налагодження визначення облікових даних для живих тестів - - Додавання нового живого тесту, специфічного для провайдера + - Додавання нового живого тесту для конкретного провайдера sidebarTitle: Live tests -summary: 'Живі тести (із доступом до мережі): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' +summary: 'Живі тести (з мережевою взаємодією): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' title: 'Тестування: живі набори тестів' x-i18n: - generated_at: "2026-04-24T19:51:02Z" + generated_at: "2026-04-24T20:32:17Z" model: gpt-5.4 provider: openai - source_hash: a221bb784b38b3dfd97c32f862f761cc9a655f904826afc181822f463bc4f753 + source_hash: 946a5f0c112cb86c45c690f62e737a8deed99440bedfcad07e8d7aabeda59495 source_path: help/testing-live.md workflow: 15 --- -Для швидкого старту, QA runners, unit/integration наборів тестів і Docker-потоків див. -[Тестування](/uk/help/testing). Ця сторінка охоплює **живі** (із доступом до мережі) набори +Щоб швидко почати, дізнатися про QA runners, набори unit/integration тестів і Docker-потоки, див. +[Тестування](/uk/help/testing). Ця сторінка охоплює **живі** (з мережевою взаємодією) набори тестів: матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також -роботу з обліковими даними. +обробку облікових даних. -## Живий режим: перевірка можливостей Android Node +## Живе тестування: перевірка можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, що наразі оголошена** підключеним Android node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не з’єднує застосунок у пару). - - Покомандна перевірка gateway `node.invoke` для вибраного Android Node. -- Обов’язкове попереднє налаштування: - - Android застосунок уже підключено та з’єднано в пару з Gateway. + - Передумови/ручне налаштування (набір тестів не встановлює, не запускає і не спаровує застосунок). + - Перевірка `node.invoke` Gateway для вибраного Android node команда за командою. +- Обов’язкова попередня підготовка: + - Android-застосунок уже підключений і спарений із Gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. + - Для можливостей, які мають проходити перевірку, надано дозволи/згоду на захоплення. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Живий режим: smoke-тест моделі (ключі профілю) +## Живе тестування: smoke-тест моделі (ключі профілю) -Живі тести розділено на два рівні, щоб можна було ізолювати збої: +Живі тести поділено на два рівні, щоб можна було ізолювати збої: -- «Безпосередня модель» показує, чи може провайдер/модель взагалі відповісти з указаним ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сеанси, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, що провайдер/модель узагалі може відповісти з наданим ключем. +- «Gateway smoke» показує, що для цієї моделі працює повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: Безпосереднє завершення моделлю (без gateway) +### Рівень 1: Безпосереднє завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і цільові регресійні перевірки, де потрібно) + - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Запустити невелике завершення для кожної моделі (і цільові регресійні перевірки за потреби) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір тестів; інакше його буде пропущено, щоб зберегти фокус `pnpm test:live` на gateway smoke -- Як вибрати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви запускаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір тестів; інакше він буде пропущений, щоб у `pnpm test:live` фокус залишався на smoke-тестах gateway +- Як вибирати моделі: + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all перевірок за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. - - Для вичерпних перевірок використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього тесту безпосередньої моделі. За замовчуванням: 60 хвилин. - - За замовчуванням перевірки безпосередньої моделі виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. -- Як вибрати провайдерів: + - Для modern/all-перевірок за замовчуванням використовується підібране обмеження з високим інформаційним сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. + - Для вичерпних перевірок використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього direct-model тесту. Значення за замовчуванням: 60 хвилин. + - Direct-model перевірки за замовчуванням виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. +- Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні значення з env + - За замовчуванням: сховище профілів і резервні env-значення - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламано / ключ недійсний» від «конвеєр gateway agent зламано» - - Містить невеликі ізольовані регресії (приклад: повторення міркувань OpenAI Responses/Codex Responses + потоки виклику інструментів) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить малі ізольовані регресії (приклад: повторне відтворення міркувань OpenAI Responses/Codex Responses + потоки виклику інструментів) -### Рівень 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Рівень 2: smoke-тест Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process Gateway - - Створити/пропатчити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по моделях із ключами та перевіряти: + - Підняти gateway у межах процесу + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Перебрати моделі з ключами і перевірити: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (перевірка read) + - що працює справжній виклик інструмента (перевірка read) - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що регресійні шляхи OpenAI (лише виклик інструмента → подальший крок) продовжують працювати -- Подробиці перевірок (щоб можна було швидко пояснювати збої): - - перевірка `read`: тест записує nonce-файл у workspace і просить agent виконати `read` цього файлу та повернути nonce. - - перевірка `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - перевірка зображення: тест додає згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. + - що регресійні шляхи OpenAI (лише виклик інструмента → наступний крок) і далі працюють +- Подробиці перевірок (щоб ви могли швидко пояснити збої): + - перевірка `read`: тест записує nonce-файл у робочу область і просить agent виконати `read` цього файлу та повернути nonce назад. + - перевірка `exec+read`: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` прочитати його назад. + - перевірка зображення: тест прикріплює згенерований 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.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway-перевірок за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. -- Як вибрати провайдерів (уникнути сценарію «OpenRouter everything»): + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви запускаєте Vitest напряму) +- Як вибирати моделі: + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому) для звуження + - Для modern/all gateway-перевірок за замовчуванням використовується підібране обмеження з високим інформаційним сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. +- Як вибирати провайдерів (уникнути «усе через OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Перевірки інструментів і зображень у цьому живому тесті завжди ввімкнені: - - перевірка `read` + перевірка `exec+read` (стрес-тест інструментів) - - перевірка зображення виконується, коли модель оголошує підтримку введення зображень + - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) + - перевірка зображення виконується, коли модель оголошує підтримку вхідних зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Вбудований agent передає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки дозволені) + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: @@ -112,26 +112,26 @@ openclaw models list openclaw models list --json ``` -## Живий режим: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) +## Живе тестування: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального бекенду CLI, не торкаючись вашої типової конфігурації. -- Типові значення smoke-тестів для бекенду зберігаються разом із визначенням `cli-backend.ts` у відповідному розширенні. +- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI-бекенду, не торкаючись вашої типової конфігурації. +- Типові значення smoke-тестів для конкретних бекендів розміщені у визначенні `cli-backend.ts` розширення-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Значення за замовчуванням: - - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка команди/аргументів/зображень походить із метаданих Plugin бекенду CLI, якому він належить. +- Типові значення: + - Типовий provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих Plugin бекенду CLI-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи вбудовуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість вбудовування в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий крок і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності того самого сеансу Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати справжнє вкладення-зображення (шляхи вставляються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість вставлення в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) для керування тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності однієї сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -147,7 +147,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для окремих провайдерів: ```bash pnpm test:docker:live-cli-backend:claude @@ -160,27 +160,27 @@ pnpm test:docker:live-cli-backend:gemini - Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. - Він запускає живий smoke-тест CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke-тесту CLI з відповідного розширення, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований префікс із правом запису в `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносного OAuth підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два кроки Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Цей маршрут підписки за замовчуванням вимикає перевірки Claude MCP/tool і зображень, оскільки наразі Claude маршрутизує використання сторонніх застосунків через тарифікацію за додаткове використання, а не через звичайні ліміти плану підписки. -- Живий smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий крок, крок класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Типовий smoke-тест Claude також патчить сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. +- Він визначає метадані smoke-тесту CLI з розширення-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-бекенду без збереження env-змінних API-ключа Anthropic. Ця підмножина для subscription за замовчуванням вимикає перевірки Claude MCP/tool і зображень, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra usage, а не через звичайні ліміти subscription-плану. +- Живий smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід із класифікацією зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke-тест Claude також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає раніше залишену нотатку. -## Живий режим: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) +## Живе тестування: smoke-тест ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із живим ACP agent: +- Мета: перевірити реальний потік прив’язки розмови ACP з живим ACP agent: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайне подальше повідомлення в тій самій розмові - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаного сеансу ACP + - надіслати звичайне продовження в тій самій розмові + - перевірити, що продовження потрапляє в транскрипт прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Значення за замовчуванням: +- Типові значення: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст розмови в стилі особистих повідомлень Slack - - Бекенд ACP: `acpx` + - Синтетичний канал: контекст розмови у стилі Slack DM + - ACP-бекенд: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -190,8 +190,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - Примітки: - - У цьому маршруті використовується поверхня gateway `chat.send` з адміністративними полями synthetic originating-route, щоб тести могли приєднувати контекст каналу повідомлень, не вдаючи зовнішню доставку. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр agents Plugin `acpx` для вибраного ACP harness agent. + - Ця підмножина використовує поверхню gateway `chat.send` з полями synthetic originating-route, доступними лише адміністратору, щоб тести могли приєднати контекст каналу повідомлень без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent вбудованого Plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -207,7 +207,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent: +Docker-рецепти для окремих agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -218,26 +218,26 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: - Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke-тест прив’язки ACP послідовно для всіх підтримуваних живих CLI agents: `claude`, `codex`, потім `gemini`. +- За замовчуванням він запускає smoke-тест ACP bind для всіх підтримуваних живих CLI agent послідовно: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, розміщує відповідний матеріал автентифікації CLI в контейнері, установлює `acpx` у npm-префікс із правом запису, а потім установлює запитуваний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підвантаженого profile доступними для дочірнього harness CLI. +- Він завантажує `~/.profile`, розміщує відповідний матеріал автентифікації CLI у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює запитаний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker runner установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого профілю доступними для дочірнього harness CLI. -## Живий режим: smoke-тест harness app-server Codex +## Живе тестування: smoke-тест harness app-server Codex - Мета: перевірити Codex harness, що належить Plugin, через звичайний метод gateway `agent`: - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший крок gateway agent до `openai/gpt-5.2` із примусово - ввімкненим Codex harness - - надіслати другий крок до того самого сеансу OpenClaw і перевірити, що потік - app-server можна відновити - - виконати `/codex status` і `/codex models` через той самий шлях - команди gateway - - за потреби виконати дві ескальовані shell-перевірки, переглянуті Guardian: одну - безпечну команду, яку має бути схвалено, і одне фальшиве завантаження секрету, - яке має бути відхилено, щоб agent перепитав + - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусово + увімкненим Codex harness + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що + потік app-server можна відновити + - запустити `/codex status` і `/codex models` через той самий шлях gateway + command + - за потреби запустити дві Guardian-перевірені shell-перевірки з підвищеними правами: одну безпечну + команду, яку слід схвалити, і одну фальшиву спробу вивантаження секрету, яку слід + відхилити, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.2` @@ -245,9 +245,9 @@ pnpm test:docker:live-acp-bind:gemini - Необов’язкова перевірка MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` - Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти перевірку, непомітно переключившись на PI. -- Автентифікація: автентифікація Codex app-server із локального входу в підписку Codex. - Docker smoke-тести також можуть передавати `OPENAI_API_KEY` для не-Codex перевірок, де це застосовно, + harness не міг пройти перевірку через тихий fallback до PI. +- Автентифікація: автентифікація app-server Codex із локального входу в підписку Codex. Docker + smoke-тести також можуть надавати `OPENAI_API_KEY` для не-Codex перевірок, де це застосовно, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -272,21 +272,21 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: - Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони є, установлює `@openai/codex` у змонтований npm - префікс із правом запису, готує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. +- Він завантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли автентифікації Codex CLI, + якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm- + префікс, розміщує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. - У Docker перевірки зображення, MCP/tool і Guardian увімкнені за замовчуванням. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфігурації живого - тесту, щоб застарілі псевдоніми або fallback на PI не могли приховати регресію +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і в конфігурації живого + тесту, щоб legacy aliases або fallback до PI не могли приховати регресію Codex harness. ### Рекомендовані живі рецепти -Вузькі, явні allowlist — найшвидші та найменш схильні до збоїв: +Вузькі, явні allowlist — найшвидші й найменш схильні до збоїв: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -304,19 +304,19 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (ключ API). -- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint agent у стилі Cloud Code Assist). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). - `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація ключем API / профілем); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація через ключ API / профіль); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розходження версій). -## Живий режим: матриця моделей (що ми охоплюємо) +## Живе тестування: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (живий режим — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (живе тестування вмикається за бажанням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. ### Сучасний набір smoke-тестів (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо зберігати робочим: +Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: - OpenAI (не-Codex): `openai/gpt-5.2` - OpenAI Codex OAuth: `openai-codex/gpt-5.2` @@ -332,7 +332,7 @@ pnpm test:docker:live-codex-harness ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на кожне сімейство провайдерів: +Виберіть щонайменше одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -341,79 +341,79 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яка у вас увімкнена) +- xAI: `xai/grok-4` (або найновішу доступну) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити пробу зображення. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Aggregators / альтернативні gateway +### Агрегатори / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, яких можна включити до живої матриці (якщо у вас є облікові дані/конфігурація): +Інші провайдери, яких можна додати до живої матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoints): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зафіксувати в документації «усі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині + ті ключі, що доступні. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) Живі тести виявляють облікові дані так само, як і CLI. Практичні наслідки: - Якщо CLI працює, живі тести мають знаходити ті самі ключі. -- Якщо живий тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо живий тест повідомляє «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в живих тестах означає «ключі профілю») +- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в живих тестах мається на увазі під «ключами профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілю) -- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускає `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб проби не торкалися вашого реального host workspace. +- Каталог legacy state: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілю) +- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, legacy `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускає `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб перевірки не використовували вашу реальну робочу область хоста. -Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runner-и нижче (вони можуть змонтувати `~/.profile` у контейнер). -## Живий режим Deepgram (транскрибування аудіо) +## Живе тестування Deepgram (транскрипція аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Живий режим BytePlus coding plan +## Живе тестування BytePlus coding plan - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Живий режим ComfyUI workflow media +## Живе тестування медіапотоку ComfyUI workflow - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації Plugin + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `plugins.entries.comfy.config.` + - Корисно після змін у відправленні comfy workflow, опитуванні, завантаженнях або реєстрації Plugin -## Живий режим генерації зображень +## Живе тестування генерації зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - Перелічує кожен зареєстрований Plugin провайдера генерації зображень - - Завантажує відсутні змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Проганяє кожен налаштований провайдер через спільний runtime генерації зображень: + - Пропускає кожного налаштованого провайдера через спільний runtime генерації зображень: - `:generate` - `:edit`, коли провайдер оголошує підтримку редагування -- Поточні вбудовані провайдери, що охоплюються: +- Поточні вбудовані провайдери, які покриваються: - `fal` - `google` - `minimax` @@ -428,88 +428,88 @@ pnpm test:docker:live-codex-harness - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -Для шляху постачаного CLI додайте smoke-тест `infer` після того, як живий -тест провайдера/runtime пройде успішно: +Для шляху постаченого CLI додайте smoke-тест `infer` після того, як живий +тест provider/runtime пройде успішно: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts openclaw infer image providers --json openclaw infer image generate \ --model google/gemini-3.1-flash-image-preview \ - --prompt "Мінімалістичне пласке тестове зображення: один синій квадрат на білому тлі, без тексту." \ + --prompt "Мінімалістичне плоске тестове зображення: один синій квадрат на білому тлі, без тексту." \ --output ./openclaw-infer-image-smoke.png \ --json ``` -Це охоплює розбір аргументів CLI, визначення конфігурації/типового agent, активацію вбудованого -Plugin, відновлення залежностей runtime вбудованого комплекту на вимогу, спільний +Це покриває розбір аргументів CLI, визначення config/default-agent, активацію вбудованого +Plugin, відновлення відсутніх залежностей вбудованого runtime на вимогу, спільний runtime генерації зображень і живий запит до провайдера. -## Живий режим генерації музики +## Живе тестування генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації музики + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені режими runtime, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt + - `generate` із вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного маршруту: + - Поточне покриття в спільній підмножині: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий живий файл Comfy, а не ця спільна перевірка + - `comfy`: окремий живий файл Comfy, не ця спільна перевірка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Живий режим генерації відео +## Живе тестування генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації відео - - За замовчуванням використовує безпечний для релізу маршрут smoke-тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може суттєво збільшити час релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його - - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - За замовчуванням використовує безпечний для релізу шлях smoke-тесту: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і обмеження часу операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - За замовчуванням запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні зображення на основі buffer у спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні відео на основі buffer у спільній перевірці - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільній перевірці: - - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення - - Покриття Vydra, специфічне для провайдера: + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне вхідне зображення на основі буфера в межах спільної перевірки + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне вхідне відео на основі буфера в межах спільної перевірки + - Поточні провайдери `imageToVideo`, які оголошені, але пропускаються у спільній перевірці: + - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення + - Покриття Vydra для конкретного провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає маршрут `veo3` text-to-video, а також маршрут `kling`, який за замовчуванням використовує fixture із віддаленим URL зображення + - цей файл запускає `veo3` text-to-video, а також підмножину `kling`, яка за замовчуванням використовує fixture із віддаленим URL зображення - Поточне живе покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільній перевірці: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі потребують віддалених URL-посилань `http(s)` / MP4 - - `google`, оскільки поточний спільний маршрут Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається в спільній перевірці - - `openai`, оскільки поточному спільному маршруту бракує гарантій доступу до video inpaint/remix, специфічних для org + - Поточні провайдери `videoToVideo`, які оголошені, але пропускаються у спільній перевірці: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені референсні URL `http(s)` / MP4 + - `google`, оскільки поточна спільна підмножина Gemini/Veo використовує локальні вхідні дані на основі буфера, а цей шлях не приймається у спільній перевірці + - `openai`, оскільки поточна спільна підмножина не гарантує доступ до video inpaint/remix, специфічний для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, зокрема FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера в типову перевірку, зокрема FAL - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження часу операції для кожного провайдера під час агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Harness для живих медіатестів +## Медіа live harness - Команда: `pnpm test:live:media` - Призначення: - Запускає спільні живі набори тестів для зображень, музики та відео через один вбудований у репозиторій entrypoint - - Автоматично завантажує відсутні змінні середовища провайдера з `~/.profile` + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, які наразі мають придатну автентифікацію - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою - Приклади: @@ -520,4 +520,4 @@ runtime генерації зображень і живий запит до пр ## Пов’язане -- [Тестування](/uk/help/testing) — unit, integration, QA і Docker набори тестів +- [Тестування](/uk/help/testing) — набори unit-, integration-, QA- і Docker-тестів diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index 42d454297..5af324235 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -7,29 +7,29 @@ sidebarTitle: Getting Started summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини title: Створення Plugin-ів x-i18n: - generated_at: "2026-04-24T19:51:43Z" + generated_at: "2026-04-24T20:32:17Z" model: gpt-5.4 provider: openai - source_hash: 5990f94cb404820f731070eb7454da26b160b3be56626476a062e4668cd9de6b + source_hash: fc6a4b97c403d7d381fae13e3815737a4b21144755e924bdf9d63c22d4cac844 source_path: plugins/building-plugins.md workflow: 15 --- -Plugin-і розширюють OpenClaw новими можливостями: канали, провайдери моделей, -мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація -зображень, генерація відео, web fetch, web search, інструменти агента або будь-яка -комбінація. +Plugin-и розширюють OpenClaw новими можливостями: канали, провайдери моделей, +мовлення, транскрибування в реальному часі, голос у реальному часі, розуміння медіа, генерація +зображень, генерація відео, отримання вебданих, вебпошук, інструменти агентів або +будь-яка комбінація. Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою -`openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub і -автоматично переходить до npm, якщо це потрібно. +`openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub, а +потім автоматично переходить до npm. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для Plugin-ів у репозиторії: репозиторій клоновано й виконано `pnpm install` +- Для Plugin-ів у репозиторії: клонований репозиторій і виконано `pnpm install` ## Який тип Plugin-а? @@ -38,23 +38,23 @@ Plugin-і розширюють OpenClaw новими можливостями: Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - Додайте провайдера моделей (LLM, проксі або кастомну кінцеву точку) + Додайте провайдера моделей (LLM, проксі або власний endpoint) - Зареєструйте інструменти агента, hook-и подій або сервіси — продовження нижче + Зареєструйте інструменти агента, event hooks або сервіси — продовження нижче -Для Plugin-а каналу, який не гарантовано буде встановлено під час запуску -налаштування/onboarding, використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування + майстра, -яка повідомляє про вимогу встановлення і завершується в закритому режимі під час реальних записів конфігурації, +Для Plugin-а каналу, який не гарантовано буде встановлений під час виконання +onboarding/setup, використовуйте `createOptionalChannelSetupSurface(...)` з +`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера setup + wizard, +яка повідомляє про вимогу встановлення та блокує реальні записи конфігурації, доки Plugin не буде встановлено. ## Швидкий старт: Plugin інструмента -У цьому прикладі створюється мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів каналів -і провайдерів є окремі посібники, посилання на які наведено вище. +Цей посібник створює мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів +каналів і провайдерів є окремі посібники за посиланнями вище. @@ -91,9 +91,9 @@ Plugin-і розширюють OpenClaw новими можливостями: ``` - Кожному Plugin-у потрібен маніфест, навіть без конфігурації. Повну схему див. у - [Маніфест](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub - розміщені в `docs/snippets/plugin-publish/`. + Кожному Plugin-у потрібен маніфест, навіть якщо в ньому немає конфігурації. Див. + [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти публікації в ClawHub + містяться в `docs/snippets/plugin-publish/`. @@ -121,15 +121,15 @@ Plugin-і розширюють OpenClaw новими можливостями: }); ``` - `definePluginEntry` призначено для Plugin-ів, які не є каналами. Для каналів використовуйте - `defineChannelPluginEntry` — див. [Plugin-и каналів](/uk/plugins/sdk-channel-plugins). - Повний перелік параметрів точки входу див. у [Точки входу](/uk/plugins/sdk-entrypoints). + `definePluginEntry` призначений для Plugin-ів, які не є каналами. Для каналів використовуйте + `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). + Повний список параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints). - **Зовнішні Plugin-и:** виконайте перевірку й опублікуйте через ClawHub, а потім встановіть: + **Зовнішні Plugin-и:** виконайте перевірку та опублікуйте через ClawHub, а потім встановіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -137,10 +137,10 @@ Plugin-і розширюють OpenClaw новими можливостями: openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів на кшталт + OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, таких як `@myorg/openclaw-my-plugin`. - **Plugin-и в репозиторії:** розмістіть їх у дереві робочого простору bundled Plugin-ів — вони виявляються автоматично. + **Plugin-и в репозиторії:** розмістіть у дереві workspace вбудованих Plugin-ів — вони будуть виявлені автоматично. ```bash pnpm test -- /my-plugin/ @@ -151,71 +151,72 @@ Plugin-і розширюють OpenClaw новими можливостями: ## Можливості Plugin-а -Один Plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`: +Один Plugin може реєструвати будь-яку кількість можливостей через об’єкт `api`: -| Можливість | Метод реєстрації | Детальний посібник | -| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ | -| Текстовий inference (LLM) | `api.registerProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins) | -| Бекенд inference CLI | `api.registerCliBackend(...)` | [Бекенди CLI](/uk/gateway/cli-backends) | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Plugin-и каналів](/uk/plugins/sdk-channel-plugins) | -| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web fetch | `api.registerWebFetchProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web search | `api.registerWebSearchProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | -| Інструменти агента | `api.registerTool(...)` | Нижче | -| Кастомні команди | `api.registerCommand(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | -| Hook-и Plugin-а | `api.on(...)` | [Hook-и Plugin-а](/uk/plugins/hooks) | -| Внутрішні hook-и подій | `api.registerHook(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | -| HTTP-маршрути | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) | -| Підкоманди CLI | `api.registerCli(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | +| Можливість | Метод реєстрації | Докладний посібник | +| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- | +| Текстова інференція (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | +| Backend інференції CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) | +| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | +| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) | +| Інструменти агентів | `api.registerTool(...)` | Нижче | +| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) | +| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -Повний API реєстрації див. у [Огляд SDK](/uk/plugins/sdk-overview#registration-api). +Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api). -Використовуйте `api.registerAgentToolResultMiddleware(...)`, коли Plugin-у потрібне асинхронне -переписування результату інструмента до того, як модель побачить вивід. Оголошуйте цільові -harness-и в `contracts.agentToolResultMiddleware`, наприклад -`["pi", "codex-app-server"]`. Віддавайте перевагу звичайним hook-ам Plugin-ів OpenClaw, якщо -робота не потребує часу результату інструмента до моделі. +Вбудовані Plugin-и можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм +потрібне асинхронне переписування результатів інструментів до того, як модель побачить вивід. Вкажіть +цільові harnesses у `contracts.agentToolResultMiddleware`, наприклад +`["pi", "codex-app-server"]`. Це довірений механізм для вбудованих Plugin-ів; зовнішнім +Plugin-ам варто надавати перевагу звичайним Plugin hooks OpenClaw, якщо тільки OpenClaw не отримає +явну політику довіри для цієї можливості. -Якщо ваш Plugin реєструє кастомні RPC-методи Gateway, зберігайте їх у -префіксі, специфічному для Plugin-а. Простори назв адміністратора ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди прив’язуються до -`operator.admin`, навіть якщо Plugin запитує вужчу область. +Якщо ваш Plugin реєструє користувацькі методи gateway RPC, використовуйте +префікс, специфічний для Plugin-а. Простори імен адміністрування ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди відповідають +`operator.admin`, навіть якщо Plugin запитує вужчу область доступу. -Семантика guard hook-ів, яку варто пам’ятати: +Семантика захисту hooks, про яку слід пам’ятати: -- `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` вважається відсутністю рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує в користувача схвалення через оверлей схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. -- `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` вважається відсутністю рішення. -- `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` вважається відсутністю рішення. -- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. -- `message_sending`: віддавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId` замість ключів metadata, специфічних для каналу. +- `before_tool_call`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує у користувача підтвердження через overlay підтвердження exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. +- `before_install`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. +- `before_install`: `{ block: false }` розглядається як відсутність рішення. +- `message_sending`: `{ cancel: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення. +- `message_received`: надавайте перевагу типізованому полю `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. +- `message_sending`: надавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId`, а не ключам metadata, специфічним для каналу. -Команда `/approve` обробляє як exec, так і схвалення Plugin-ів з обмеженим fallback: коли id схвалення exec не знайдено, OpenClaw повторно пробує той самий id через схвалення Plugin-ів. Переспрямування схвалення Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації. +Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin-ів з обмеженим fallback: якщо ідентифікатор підтвердження exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через підтвердження Plugin-ів. Переспрямування підтверджень Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації. -Якщо кастомна логіка схвалення має виявляти той самий випадок обмеженого fallback, -віддавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` -замість ручного зіставлення рядків завершення строку дії схвалення. +Якщо користувацька логіка підтвердження має визначати той самий випадок обмеженого fallback, +використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` +замість ручного зіставлення рядків закінчення терміну підтвердження. -Див. [Hook-и Plugin-а](/uk/plugins/hooks), щоб переглянути приклади та довідник hook-ів. +Приклади й довідник hooks див. у [Plugin hooks](/uk/plugins/hooks). -## Реєстрація інструментів агента +## Реєстрація інструментів агентів Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди -доступними) або необов’язковими (користувач вмикає їх за бажанням): +доступні) або необов’язковими (користувач сам вмикає їх): ```typescript register(api) { - // Обов’язковий інструмент — завжди доступний + // Required tool — always available api.registerTool({ name: "my_tool", description: "Do a thing", @@ -225,7 +226,7 @@ register(api) { }, }); - // Необов’язковий інструмент — користувач має додати його до allowlist + // Optional tool — user must add to allowlist api.registerTool( { name: "workflow_tool", @@ -248,11 +249,11 @@ register(api) { } ``` -- Назви інструментів не мають конфліктувати з інструментами ядра (конфлікти пропускаються) +- Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються) - Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів -- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши id Plugin-а до `tools.allow` +- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши ідентифікатор Plugin-а до `tools.allow` -## Угоди щодо імпорту +## Угоди щодо імпортів Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/`: @@ -260,76 +261,76 @@ register(api) { import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; -// Неправильно: монолітний корінь (застаріло, буде видалено) +// Wrong: monolithic root (deprecated, will be removed) import { ... } from "openclaw/plugin-sdk"; ``` -Повний довідник підшляхів див. у [Огляд SDK](/uk/plugins/sdk-overview). +Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview). У межах вашого Plugin-а використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK. -Для Plugin-ів провайдерів зберігайте допоміжні засоби, специфічні для провайдера, у цих barrel-файлах -кореня пакета, якщо тільки межа справді не є загальною. Поточні bundled приклади: +Для Plugin-ів провайдерів зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах +кореня пакета, якщо тільки цей механізм не є справді загальним. Поточні вбудовані приклади: - Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta -- OpenAI: конструктори провайдерів, допоміжні засоби моделей за замовчуванням, провайдери реального часу -- OpenRouter: конструктор провайдера плюс допоміжні засоби onboarding/конфігурації +- OpenAI: конструктори провайдерів, допоміжні засоби для моделей за замовчуванням, провайдери реального часу +- OpenRouter: конструктор провайдера плюс допоміжні засоби onboarding/config -Якщо допоміжний засіб корисний лише всередині одного bundled пакета провайдера, залишайте його на цьому -package-root seam замість того, щоб переносити в `openclaw/plugin-sdk/*`. +Якщо допоміжний засіб корисний лише в межах одного пакета вбудованого провайдера, залишайте його +на цьому рівні пакета замість перенесення до `openclaw/plugin-sdk/*`. -Деякі згенеровані helper seam-и `openclaw/plugin-sdk/` усе ще існують для -підтримки bundled Plugin-ів і сумісності, наприклад -`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Ставтеся до них як до зарезервованих -поверхонь, а не як до типової схеми для нових сторонніх Plugin-ів. +Деякі згенеровані механізми допоміжних засобів `openclaw/plugin-sdk/` усе ще існують для +підтримки вбудованих Plugin-ів і сумісності, наприклад +`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані +поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів. ## Контрольний список перед поданням -**package.json** має правильні метадані `openclaw` -Маніфест **openclaw.plugin.json** наявний і коректний +**package.json** має коректні метадані `openclaw` +Маніфест **openclaw.plugin.json** присутній і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` Усі імпорти використовують цільові шляхи `plugin-sdk/` -Внутрішні імпорти використовують локальні модулі, а не self-import-и SDK +Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK Тести проходять (`pnpm test -- /my-plugin/`) `pnpm check` проходить (для Plugin-ів у репозиторії) -## Тестування бета-релізу +## Тестування beta-релізів -1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw), щоб отримувати анонси релізів. -2. Протестуйте свій Plugin із бета-тегом щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин. +1. Слідкуйте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів. +2. Протестуйте свій Plugin на beta-тегу щойно він з’явиться. Вікно до stable зазвичай становить лише кілька годин. 3. Після тестування напишіть у гілці вашого Plugin-а в каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. -4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і додайте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. -5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у вашій гілці Discord. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для супровідників і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити в реліз. Під час бета-тестування супровідники стежать за цими гілками. -6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустили це вікно, ваше виправлення, ймовірно, потрапить у наступний цикл. +4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у вашій гілці Discord. Учасники не можуть ставити мітки на PR, тому назва є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити в реліз. Під час beta-тестування мейнтейнери стежать за цими гілками. +6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить уже в наступний цикл. -## Наступні кроки +## Подальші кроки - + Створіть Plugin каналу обміну повідомленнями - + Створіть Plugin провайдера моделей Карта імпортів і довідник API реєстрації - - TTS, search, subagent через api.runtime + + TTS, пошук, subagent через api.runtime - Утиліти й шаблони для тестування + Утиліти та шаблони тестування - Повний довідник схеми маніфесту + Повний довідник зі схеми маніфесту ## Пов’язане -- [Архітектура Plugin-ів](/uk/plugins/architecture) — детальний огляд внутрішньої архітектури -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin-ів -- [Маніфест](/uk/plugins/manifest) — формат маніфесту plugin-а -- [Plugin-и каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів -- [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів +- [Plugin Architecture](/uk/plugins/architecture) — детальний огляд внутрішньої архітектури +- [SDK Overview](/uk/plugins/sdk-overview) — довідник SDK Plugin-ів +- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin-а +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 02c41c07c..f77a6654e 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -2,63 +2,64 @@ read_when: - Ви створюєте Plugin для OpenClaw - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації) -title: Маніфест Plugin +summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) +title: маніфест Plugin x-i18n: - generated_at: "2026-04-24T20:18:19Z" + generated_at: "2026-04-24T20:32:16Z" model: gpt-5.4 provider: openai - source_hash: 6b2849737f9d785ff15a7988cfaf6515cbabce2901e2da4f2c72007d302f41f2 + source_hash: 319836cd179aac8a194f8b5b4fee230566ee8b02ce13068c0d8a221d032b4907 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. +Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**. -Сумісні компонування пакетів описано тут: [Пакети Plugin](/uk/plugins/bundles). +Сумісні компонування пакетів описані в [пакетах Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфесту: - Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude +- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонента Claude без маніфесту - Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію +OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені -корені навичок, корені команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude та підтримувані набори хуків, коли компонування -відповідає очікуванням рантайму OpenClaw. +Для сумісних пакетів OpenClaw наразі читає метадані пакета разом із оголошеними +коренями Skills, коренями команд Claude, типовими значеннями `settings.json` пакета Claude, +типовими значеннями LSP пакета Claude та підтримуваними наборами хуків, якщо компонування +відповідає очікуванням середовища виконання OpenClaw. -Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у -**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються +Кожен власний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у +**корені Plugin**. OpenClaw використовує цей маніфест, щоб валідовати конфігурацію +**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin). -Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл `openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду -вашого Plugin**. Усе нижче має бути достатньо недорогим для перевірки без запуску -рантайму Plugin. +вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску +середовища виконання Plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь control-plane -- скороченого володіння сімействами моделей +- ідентифікації Plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь control plane +- володіння скороченими сімействами моделей - статичних знімків володіння можливостями (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для каналу, що об’єднуються в каталог і поверхні валідації +- метаданих конфігурації для конкретних каналів, об’єднаних у каталозі та поверхнях валідації -**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду -або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення +точок входу коду або метаданих встановлення npm. Це має належати коду вашого Plugin +і `package.json`. ## Мінімальний приклад @@ -140,68 +141,68 @@ OpenClaw також автоматично визначає ці компону | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | +| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим типово. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. | -| `modelSupport` | Ні | `object` | Короткі метадані сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску рантайму. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження рантайму провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або бекенд CLI, для яких слід перевіряти синтетичний хук автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження рантайму. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення API-ключів-заповнювачів, що належать вбудованому Plugin і позначають несекретний локальний стан, стан OAuth або стан ambient credentials. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час вікна знецінення. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який використовує той самий API-ключ базового провайдера й auth profiles. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити типові хелпери запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою все одно володіє рантайм Plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження рантайму Plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які повинні автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Id каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдерів, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | +| `modelSupport` | Ні | `object` | Належні маніфесту скорочені метадані сімейств моделей, які використовуються для автозавантаження Plugin до етапу виконання. | +| `providerEndpoints` | Ні | `object[]` | Належні маніфесту метадані хостів/`baseUrl` кінцевих точок для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. | +| `cliBackends` | Ні | `string[]` | Id backend CLI inference, якими володіє цей Plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких слід перевіряти належний Plugin synthetic auth hook під час холодного виявлення моделей до завантаження середовища виконання. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, які належать вбудованому Plugin і представляють несекретний локальний стан, стан OAuth або облікові дані середовища. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin, і які мають породжувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/стану провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час вікна зворотної сумісності перед вилученням. | +| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер кодування, який використовує той самий API-ключ базового провайдера та ті самі профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для каналів, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації на основі env, які мають бачити загальні хелпери запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення бажаного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, яке запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою все одно володіє середовище виконання Plugin. | +| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх auth hook, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення media-understanding для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Належні маніфесту метадані конфігурації каналів, які об’єднуються в поверхнях виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skill для завантаження, відносні до кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | | `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | | `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | +| `uiHints` | Ні | `Record` | Підписи UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження рантайму провайдера. +OpenClaw читає це до завантаження середовища виконання провайдера. Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності -переходить до метаданих майстра рантайму та варіантів каталогу встановлення. +переходить до метаданих wizard середовища виконання та варіантів каталогу встановлення. | Поле | Обов’язкове | Тип | Що воно означає | | --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, що використовується потоками онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але все одно дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямовувати. | +| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | +| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. | | `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | | `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | | `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | | `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | +| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типовим значенням є `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою команди рантайму, яку користувачі можуть +Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду рантайму Plugin. +використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. ```json { @@ -215,34 +216,34 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо така є. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може з низькими витратами оголосити, які події control-plane +Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку рантайму, не замінює `register(...)` і не обіцяє, що код -Plugin уже виконувався. Планувальник активації використовує ці поля для звуження -кандидатів Plugin перед переходом до наявних метаданих володіння з маніфесту, таких як -`providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. +Цей блок — метадані планувальника, а не API життєвого циклу. Він не реєструє +поведінку під час виконання, не замінює `register(...)` і не обіцяє, що код +Plugin уже виконано. Планувальник активації використовує ці поля, щоб +звузити набір кандидатів Plugin, перш ніж перейти до наявних метаданих володіння маніфесту, +таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і hooks. -Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок планувальника, -які не можна представити цими полями володіння. +коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, +які не можна подати через ці поля володіння. -Цей блок є лише метаданими. Він не реєструє поведінку рантайму і не -замінює `register(...)`, `setupEntry` або інші точки входу рантайму/Plugin. +Цей блок — лише метадані. Він не реєструє поведінку під час виконання і не +замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має -змінювати коректність, поки ще існують застарілі fallback-механізми володіння з маніфесту. +відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не повинна +змінювати коректність, поки ще існують застарілі резервні механізми володіння маніфесту. ```json { @@ -256,37 +257,37 @@ Plugin уже виконувався. Планувальник активаці } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control-plane. Якщо можливо, надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Id провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onCommands` | Ні | `string[]` | Id команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Id каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control plane. За можливості віддавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні live-споживачі: -- планування CLI, що запускається командою, повертається до застарілих +- планування CLI, запущене командою, використовує застарілий резервний механізм `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/каналу, що запускається каналом, повертається до застарілого володіння - `channels[]`, якщо явні метадані активації каналу відсутні -- планування setup/рантайму, що запускається провайдером, повертається до застарілого - володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані активації - провайдера відсутні +- планування setup/каналу, запущене каналом, використовує застарілий резервний механізм володіння `channels[]`, + коли явні метадані активації каналу відсутні +- планування setup/середовища виконання, запущене провайдером, використовує застарілий резервний механізм + `providers[]` і володіння верхнього рівня `cliBackends[]`, коли явні метадані активації провайдера + відсутні -Діагностика планувальника може відрізняти явні підказки активації від fallback-механізму -володіння з маніфесту. Наприклад, `activation-command-hint` означає, що +Діагностика планувальника може розрізняти явні підказки активації та резервний +механізм володіння маніфесту. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння з `commandAliases`. Ці мітки причин призначені для -діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, +планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для +діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати ті метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під спільний -корінь `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI -усе одно володіє рантайм Plugin через полегшену поверхню -`runtime-api.ts`, що експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під +спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими та статичними; фактичною +реєстрацією CLI все одно володіє середовище виконання Plugin через легковагову +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -299,15 +300,15 @@ Plugin уже виконувався. Планувальник активаці } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | --------------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані, -що належать Plugin, до завантаження рантайму. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, +що належать Plugin, до завантаження середовища виконання. ```json { @@ -326,54 +327,53 @@ Plugin уже виконувався. Планувальник активаці } ``` -`cliBackends` верхнього рівня залишається допустимим і й надалі описує -бекенди інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, -для потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається валідним і далі описує backend CLI inference. +`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для +потоків control plane/setup, які мають залишатися лише метаданими. -Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною -поверхнею пошуку для виявлення setup на основі дескрипторів. Якщо дескриптор лише -звужує кандидата Plugin, а setup усе ще потребує багатших хуків рантайму на етапі setup, -задайте `requiresRuntime: true` і залиште `setup-api` як -fallback-шлях виконання. +Коли присутні `setup.providers` і `setup.cliBackends`, вони є бажаною +поверхнею пошуку, що спочатку спирається на дескриптори, для виявлення setup. Якщо дескриптор лише +звужує кандидатний Plugin, а для setup все ще потрібні багатші hooks середовища виконання на етапі setup, +встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та -env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом -періоду знецінення, але невбудовані Plugin, які все ще його використовують, -отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу -в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера +та env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +під час перехідного періоду перед вилученням, але невбудовані Plugin, які все ще використовують його, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для +setup/стану в `setup.providers[].envVars`. -Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори -і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime` -не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали дескриптори -без цього прапорця, не зламалися. +і не виконуватиме `setup-api` для пошуку setup. Пропущений `requiresRuntime` +зберігає застарілу резервну поведінку, щоб наявні Plugin, які додали дескриптори +без цього прапорця, не ламалися. Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися -унікальними серед виявлених Plugin. Неоднозначне володіння призводить до безпечної відмови, -замість вибору переможця за порядком виявлення. +унікальними серед усіх виявлених Plugin. Неоднозначне володіння завершується +закритою відмовою замість вибору переможця за порядком виявлення. -Коли рантайм setup усе ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, -якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено в дескрипторах -маніфесту, або якщо для дескриптора немає відповідної реєстрації в рантаймі. -Ця діагностика є додатковою і не відхиляє застарілі Plugin. +Коли середовище виконання setup все ж виконується, діагностика реєстру setup повідомляє про +розбіжність дескрипторів, якщо `setup-api` реєструє провайдер або backend CLI, який +дескриптори маніфесту не оголошують, або якщо дескриптор не має відповідної реєстрації +під час виконання. Ці діагностики є додатковими й не відхиляють застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/статусу можуть перевіряти до завантаження рантайму Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | +| `id` | Так | `string` | Id провайдера, який показується під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. | +| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/стану можуть перевіряти до завантаження середовища виконання Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів для етапу setup, що використовуються для пошуку setup спочатку за дескрипторами. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, які показуються під час setup і онбордингу. | +| `cliBackends` | Ні | `string[]` | Id backend для етапу setup, які використовуються для пошуку setup, що спирається спочатку на дескриптори. Зберігайте нормалізовані id глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup все ще виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` @@ -394,19 +394,19 @@ env vars. `providerAuthEnvVars` залишається підтримувани Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | ------------------------------------- | +| `label` | `string` | Підпис поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -зчитувати без імпорту рантайму Plugin. +зчитати без імпорту середовища виконання Plugin. ```json { @@ -429,43 +429,45 @@ env vars. `providerAuthEnvVars` залишається підтримувани Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------ | -| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих розширень. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори harness, для яких цей Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хуком зовнішнього auth profile яких володіє цей Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | -| `tools` | `string[]` | Назви agent tools, якими володіє цей Plugin для перевірок вбудованих контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Застарілі id фабрик вбудованих extension. | +| `agentToolResultMiddleware` | `string[]` | Id harness, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Id провайдерів, external auth profile hook яких належить цьому Plugin. | +| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime transcription, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime voice, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Id провайдерів embedding пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Id провайдерів image generation, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Id провайдерів video generation, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей Plugin. | +| `tools` | `string[]` | Назви агентних інструментів, якими володіє цей Plugin, для перевірок контрактів вбудованих компонентів. | -`contracts.embeddedExtensionFactories` збережено для вбудованого коду сумісності, -якому все ще потрібні прямі події вбудованого runner Pi. Нові трансформації -результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися -через `api.registerAgentToolResultMiddleware(...)`. +`contracts.embeddedExtensionFactories` збережено для коду сумісності вбудованих компонентів, +якому все ще потрібні прямі події Pi embedded-runner. Нові вбудовані +трансформації результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` +і реєструватися через `api.registerAgentToolResultMiddleware(...)`. +Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки цей шов може +переписувати високодовірений вивід інструментів до того, як його побачить модель. -Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати -`contracts.externalAuthProviders`. Plugins без цього оголошення все ще працюють -через застарілий fallback-механізм сумісності, але він повільніший і -буде видалений після завершення періоду міграції. +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати +`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють +через застарілий резервний механізм сумісності, але він повільніший і +буде вилучений після завершення перехідного вікна. -Вбудовані провайдери memory embedding повинні оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з -вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише Plugin-власник до того, як повний рантайм Gateway зареєструє -провайдерів. +Вбудовані провайдери embedding пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, зокрема +для вбудованих адаптерів, таких як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, +щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway +зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має -типові моделі, пріоритет fallback-автентифікації або нативну підтримку документів, які -потрібні загальним хелперам ядра до завантаження рантайму. Ключі також мають бути оголошені в +типові моделі, пріоритет резервної автоавтентифікації або нативну підтримку документів, +які потрібні загальним хелперам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -493,15 +495,15 @@ Plugins провайдерів, які реалізують `resolveExternalAuth | Поле | Тип | Що воно означає | | ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. | -| `defaultModels` | `Record` | Типові значення моделей за можливістю, які використовуються, коли в конфігурації не вказано модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові значення модель-для-можливості, які використовуються, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | | `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до -завантаження рантайму. +Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до +завантаження середовища виконання. ```json { @@ -530,19 +532,19 @@ Plugins провайдерів, які реалізують `resolveExternalAuth Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору й інспекції, коли метадані рантайму ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, який об’єднується в поверхнях вибору та перевірки, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | +| `preferOver` | `string[]` | Id застарілих або нижчопріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin провайдера за -скороченими ідентифікаторами моделей, такими як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження -рантайму Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +скорочених id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження +середовища виконання Plugin. ```json { @@ -555,104 +557,105 @@ Plugins провайдерів, які реалізують `resolveExternalAuth OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику -- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника +- `modelPatterns` мають пріоритет над `modelPrefixes` - якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ---------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що звіряються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що звіряються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ---------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне -завантаження маніфесту більше не трактує ці поля верхнього рівня як -володіння можливостями. +завантаження маніфесту більше не вважає ці поля верхнього рівня +володінням можливостями. -## Маніфест у порівнянні з package.json +## Маніфест і `package.json` -Ці два файли виконують різні ролі: +Ці два файли виконують різні завдання: -| Файл | Для чого використовувати | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| Файл | Для чого його використовувати | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | | `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом: +Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: -- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розмістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розмістіть це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin до запуску рантайму навмисно зберігаються в `package.json` у блоці +Частина метаданих Plugin до етапу виконання навмисно зберігається в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує точки входу власного Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу рантайму built JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та пошуку стану каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, аліаси та текст для вибору. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід хоч кудись?» без завантаження повного рантайму каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих Plugin і Plugin, опублікованих зовні. | -| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють завантажений артефакт на відповідність йому. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація некоректна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує точки входу власних Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легковагова точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легковагові метадані каталогу каналів, як-от підписи, шляхи документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання каналу. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в -онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач обирає один із цих +онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження -реєстру маніфестів. Некоректні значення відхиляються; новіші, але коректні значення +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають Plugin на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +Точне закріплення версії npm уже живе в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно -завершувалися помилкою, якщо завантажений npm-артефакт більше не відповідає закріпленому релізу. -Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, -включно з голими назвами пакетів і dist-tags. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю -назви пакета та некоректні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` наявний, але немає коректного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` наявний, -потоки встановлення/оновлення примусово застосовують його; коли його не вказано, розв’язання реєстру +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися +закритою відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. +Інтерактивний онбординг усе ще пропонує npm-специфікації довіреного реєстру, включно з голими +іменами пакетів і dist-tag, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, із невідповідністю +імені пакета та невалідні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає валідного npm-джерела, яке ним можна закріпити. +Коли `expectedIntegrity` присутній, +потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру фіксується без закріплення цілісності. -Plugins каналів повинні надавати `openclaw.setupEntry`, коли для статусу, списку каналів -або перевірок SecretRef потрібно визначати налаштовані облікові записи без завантаження повного -рантайму. Точка входу setup має відкривати метадані каналу разом із безпечними для setup адаптерами -конфігурації, статусу та секретів; мережеві клієнти, слухачі gateway та -рантайми транспорту залишайте в основній точці входу розширення. +Plugin каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів +або сканування SecretRef потрібно визначити налаштовані облікові записи без завантаження повного +середовища виконання. Точка входу setup має надавати метадані каналу разом із безпечними для setup +адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і +transport runtime залишайте в основній точці входу extension. -Поля точок входу рантайму не перевизначають перевірки меж пакетів для полів -точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити -завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля точок входу runtime не перевизначають перевірки меж пакета для +полів точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може +зробити завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно -не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення -відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, таких як -відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого -вбудованого Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення й спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Він +не робить довільні зламані конфігурації придатними до встановлення. Наразі він лише дозволяє +потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого Plugin, +наприклад відсутнього шляху до вбудованого Plugin або застарілого запису `channels.` для +цього самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення +та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля-перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -668,12 +671,12 @@ Plugins каналів повинні надавати `openclaw.setupEntry`, к } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка -автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою -функцією, яка лише читає збережений стан; не маршрутизуйте її через повний barrel рантайму -каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева +перевірка автентифікації з відповіддю так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою +функцією, яка читає лише збережений стан; не спрямовуйте її через повний +barrel середовища виконання каналу. -`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: ```json @@ -690,57 +693,58 @@ Plugins каналів повинні надавати `openclaw.setupEntry`, к } ``` -Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших невеликих -невиконавчих входів. Якщо перевірка потребує повного розв’язання конфігурації або реального -рантайму каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших маленьких +невиконуваних вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або реального +середовища виконання каналу, натомість залишайте цю логіку в hook `config.hasConfiguredState` +Plugin. -## Пріоритет виявлення (дублікати ідентифікаторів Plugin) +## Пріоритет виявлення (дублікати id Plugin) -OpenClaw виявляє Plugins із кількох коренів (вбудовані, глобально встановлені, робочий простір, явно вибрані конфігурацією шляхи). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. +OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, робочий простір, явно вибрані в конфігурації шляхи). Якщо два виявлені записи мають спільний `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — Plugins, що постачаються з OpenClaw -3. **Глобальне встановлення** — Plugins, установлені в глобальний корінь Plugin OpenClaw -4. **Робочий простір** — Plugins, виявлені відносно поточного робочого простору +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — Plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw +4. **Робочий простір** — Plugin, виявлені відносно поточного робочого простору Наслідки: -- Форк або застаріла копія вбудованого Plugin у робочому просторі не зможе затінити вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. -- Відкинуті дублікати журналюються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Розгалужена або застаріла копія вбудованого Plugin у робочому просторі не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на виявлення в робочому просторі. +- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі. +- **Кожен Plugin повинен постачати JSON Schema**, навіть якщо він не приймає жодної конфігурації. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошений - у маніфесті Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено + маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. + повинні посилатися на **виявлювані** id Plugin. Невідомі id є **помилками**. - Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і - у Doctor та журналах з’являється **попередження**. +- Якщо конфігурація Plugin існує, але Plugin **вимкнений**, конфігурація зберігається і + у Doctor + журналах показується **попередження**. -Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). +Повну схему `plugins.*` див. у [довіднику конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Рантайм, як і раніше, завантажує модуль Plugin окремо; маніфест призначений лише для виявлення + валідації. -- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання все одно завантажує модуль Plugin окремо; маніфест потрібний лише для виявлення + валідації. +- Власні маніфести парсяться за допомогою JSON5, тож коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. - `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. - Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані env vars (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. -- Метадані wizard рантайму, які потребують коду провайдера, описано в [Хуках рантайму провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Метадані env vars (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. +- Метадані runtime wizard, які потребують коду провайдера, див. у [hooks середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index cd0fe05c0..189ed68a5 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,58 +1,57 @@ --- read_when: - - Ви змінюєте вбудований runtime агента або реєстр harness-а - - Ви реєструєте harness агента з вбудованого або довіреного Plugin-а - - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із провайдерами моделей + - Ви змінюєте вбудований рантайм агента або реєстр каркаса агента + - Ви реєструєте каркас агента з вбудованого або довіреного плагіна + - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для Plugin-ів, які замінюють низькорівневий вбудований виконавець агента -title: Plugin-и harness агента +summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агентів +title: Плагіни каркаса агентів x-i18n: - generated_at: "2026-04-24T19:52:03Z" + generated_at: "2026-04-24T20:32:19Z" model: gpt-5.4 provider: openai - source_hash: ffb57530e6259952c8dde473a69052f578b081f28659e22b72347fa64e497a38 + source_hash: e73cbaaa239801ec5da18374cc1b2142c9cf7136f8d33d81d2fa04bc4dea3c11 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**harness агента** — це низькорівневий виконавець для одного підготовленого -ходу агента OpenClaw. Це не провайдер моделей, не канал і не реєстр інструментів. +**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin-ів. Контракт -досі експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний -вбудований runner. +Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт +усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний +вбудований раннер. -## Коли використовувати harness +## Коли використовувати каркас -Реєструйте harness агента, коли сімейство моделей має власний нативний runtime -сеансів, а звичайний транспорт провайдера OpenClaw є хибною абстракцією. +Реєструйте каркас агента, коли сімейство моделей має власний нативний рантайм сесії +і звичайний транспорт постачальника OpenClaw є неправильною абстракцією. Приклади: -- нативний сервер coding-agent, який володіє тредами й Compaction -- локальний CLI або демон, який має стримити нативні події plan/reasoning/tool -- runtime моделі, якому потрібен власний resume id на додачу до транскрипту - сеансу OpenClaw +- нативний сервер coding-agent, який керує потоками й Compaction +- локальний CLI або демон, який має стримити нативні події плану/міркування/інструментів +- рантайм моделі, якому потрібен власний resume id на додачу до транскрипту + сесії OpenClaw -**Не** реєструйте harness лише для додавання нового API LLM. Для звичайних HTTP або -WebSocket API моделей створюйте [provider Plugin](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або +WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). -## Чим усе ще володіє core +## Що все ще належить core -До того, як буде вибрано harness, OpenClaw уже визначив: +Перш ніж буде вибрано каркас, OpenClaw уже визначив: -- провайдера і модель -- стан автентифікації runtime +- постачальника й модель +- стан автентифікації рантайму - рівень thinking і бюджет контексту -- файл транскрипту/сеансу OpenClaw -- workspace, sandbox і політику інструментів -- callback-и відповіді каналу та стримінгу -- політику fallback моделі та live-перемикання моделей +- файл транскрипту/сесії OpenClaw +- робочий простір, sandbox і політику інструментів +- колбеки відповіді каналу й колбеки стримінгу +- політику резервного перемикання моделей і live-перемикання моделей -Такий поділ навмисний. Harness виконує підготовлену спробу; він не вибирає -провайдерів, не замінює доставку каналу й не перемикає моделі непомітно. +Цей поділ навмисний. Каркас виконує підготовлену спробу; він не вибирає +постачальників, не замінює доставку через канал і не перемикає моделі непомітно. -## Реєстрація harness +## Зареєструвати каркас **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -90,111 +89,111 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає harness після визначення провайдера/моделі: +OpenClaw вибирає каркас після визначення постачальника/моделі: -1. Ідентифікатор harness, записаний у наявному сеансі, має пріоритет, щоб зміни config/env не - перемикали цей транскрипт на інший runtime на льоту. -2. `OPENCLAW_AGENT_RUNTIME=` примусово вмикає зареєстрований harness з цим id для - сеансів, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вмикає вбудований harness PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` просить зареєстровані harness-и перевірити, чи підтримують вони - визначеного провайдера/модель. -5. Якщо відповідного зареєстрованого harness-а немає, OpenClaw використовує PI, якщо fallback на PI - не вимкнено. +1. Якщо в наявної сесії записано id каркаса, він має пріоритет, тому зміни config/env не + перемикають цей транскрипт на інший рантайм на льоту. +2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований каркас із цим id для + сесій, які ще не закріплені. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих каркасів, чи підтримують вони + визначеного постачальника/модель. +5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо + резервний перехід на PI не вимкнено. -Помилки harness-ів Plugin-ів відображаються як помилки виконання. У режимі `auto` fallback на PI -застосовується лише тоді, коли жоден зареєстрований harness Plugin-а не підтримує визначеного -провайдера/модель. Щойно harness Plugin-а заявив про запуск, OpenClaw не -програє той самий хід повторно через PI, оскільки це може змінити семантику -auth/runtime або спричинити дубльовані побічні ефекти. +Збої каркасів плагінів проявляються як збої виконання. У режимі `auto` резервний перехід на PI +використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного +постачальника/модель. Щойно каркас плагіна взяв виконання на себе, OpenClaw не +переграє той самий хід через PI, оскільки це може змінити семантику автентифікації/рантайму +або дублювати побічні ефекти. -Вибраний id harness-а зберігається разом з id сеансу після вбудованого запуску. -Застарілі сеанси, створені до появи привʼязок harness-а, вважаються привʼязаними до PI, щойно в них -зʼявляється історія транскрипту. Використовуйте новий/скинутий сеанс, коли перемикаєтеся між PI і -нативним harness-ом Plugin-а. `/status` показує не типові id harness-ів, такі як `codex`, -поруч із `Fast`; PI прихований, оскільки це типовий шлях сумісності. -Якщо вибраний harness виглядає неочікуваним, увімкніть журналювання налагодження `agents/harness` і +Вибраний id каркаса зберігається разом з id сесії після вбудованого виконання. +Застарілі сесії, створені до появи закріплення каркасів, вважаються закріпленими за PI, щойно +в них з’являється історія транскрипту. Використовуйте нову/скинуту сесію під час перемикання між PI і +нативним каркасом плагіна. `/status` показує нестандартні id каркасів, як-от `codex`, +поруч із `Fast`; PI залишається прихованим, бо це шлях сумісності за замовчуванням. +Якщо вибраний каркас виглядає несподівано, увімкніть журналювання налагодження `agents/harness` і перегляньте структурований запис gateway `agent harness selected`. Він містить -id вибраного harness-а, причину вибору, політику runtime/fallback і, у режимі -`auto`, результат підтримки для кожного кандидата Plugin-а. +вибраний id каркаса, причину вибору, політику рантайму/резервного переходу, а також у режимі +`auto` — результат підтримки для кожного кандидата-плагіна. -Вбудований Plugin Codex реєструє `codex` як свій id harness-а. Core розглядає це -як звичайний id harness-а Plugin-а; специфічні для Codex псевдоніми мають належати Plugin-у -або config оператора, а не спільному селектору runtime. +Вбудований плагін Codex реєструє `codex` як свій id каркаса. Core розглядає це +як звичайний id каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну +або config оператора, а не спільному селектору рантайму. -## Поєднання provider + harness +## Поєднання постачальника й каркаса -Більшість harness-ів також мають реєструвати provider. Provider робить refs моделей, -статус auth, метадані моделі та вибір `/model` видимими для решти -OpenClaw. Потім harness заявляє цей provider у `supports(...)`. +Більшість каркасів також мають реєструвати постачальника. Постачальник робить refs моделей, +стан автентифікації, метадані моделі й вибір `/model` видимими для решти +OpenClaw. Потім каркас заявляє цей постачальник у `supports(...)`. -Вбудований Plugin Codex дотримується цього шаблону: +Вбудований плагін Codex дотримується цього шаблону: -- id provider: `codex` -- refs моделей для користувача: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; - застарілі refs `codex/gpt-*` досі приймаються для сумісності -- id harness-а: `codex` -- auth: синтетична доступність provider, оскільки harness Codex володіє - нативним входом/сеансом Codex -- запит app-server: OpenClaw надсилає до Codex чистий id моделі й дозволяє - harness-у працювати з нативним протоколом app-server +- id постачальника: `codex` +- refs моделей для користувача: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; + застарілі refs `codex/gpt-*` і далі приймаються для сумісності +- id каркаса: `codex` +- auth: синтетична доступність постачальника, оскільки каркас Codex керує + нативним входом/сесією Codex +- запит до app-server: OpenClaw надсилає Codex «голий» id моделі й дозволяє + каркасу працювати з нативним протоколом app-server -Plugin Codex є додатковим. Звичайні refs `openai/gpt-*` і далі використовують -нормальний шлях provider OpenClaw, якщо ви не примусите harness Codex через -`embeddedHarness.runtime: "codex"`. Старі refs `codex/gpt-*` і далі вибирають -provider і harness Codex для сумісності. +Плагін Codex є доповнювальним. Звичайні refs `openai/gpt-*` і далі використовують +нормальний шлях постачальника OpenClaw, якщо ви не примусите каркас Codex через +`embeddedHarness.runtime: "codex"`. Старіші refs `codex/gpt-*` усе ще вибирають +постачальника й каркас Codex для сумісності. -Налаштування для операторів, приклади префіксів моделей і config-и лише для Codex дивіться в -[Codex Harness](/uk/plugins/codex-harness). +Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex, див. +[Каркас Codex](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новіше. Plugin Codex перевіряє -initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб +OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Плагін Codex перевіряє +initialize-handshake app-server і блокує старіші або безверсійні сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. ### Middleware результатів інструментів -Plugin-и можуть підключати нейтральне щодо harness middleware для результатів інструментів через -`api.registerAgentToolResultMiddleware(...)`, коли їхній manifest оголошує -цільові id harness-ів у `contracts.agentToolResultMiddleware`. Це шов для -асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex -повернуть вивід інструмента назад у модель. +Вбудовані плагіни можуть додавати не прив’язане до каркаса middleware результатів інструментів через +`api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує +цільові id каркасів у `contracts.agentToolResultMiddleware`. Цей довірений шов +призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex передадуть +вивід інструмента назад у модель. -Застарілі вбудовані Plugin-и все ще можуть використовувати -`api.registerCodexAppServerExtensionFactory(...)` для middleware лише app-server Codex, -але нові перетворення результатів мають використовувати API, нейтральний щодо harness-а. +Застарілі вбудовані плагіни все ще можуть використовувати +`api.registerCodexAppServerExtensionFactory(...)` для middleware лише для Codex app-server, +але нові перетворення результатів мають використовувати API, не прив’язане до каркаса. Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` є застарілим для -перетворень результатів інструментів; зберігайте його лише для коду сумісності вбудованих компонентів, якому -досі потрібні прямі події embedded-runner-а Pi. +перетворень результатів інструментів; залишайте його лише для вбудованого коду сумісності, якому +все ще потрібні прямі події вбудованого раннера Pi. -### Режим нативного harness-а Codex +### Режим нативного каркаса Codex -Вбудований harness `codex` — це нативний режим Codex для вбудованих -ходів агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex` і додайте `codex` до +Вбудований каркас `codex` — це нативний режим Codex для вбудованих ходів +агента OpenClaw. Спочатку увімкніть вбудований плагін `codex` і додайте `codex` до `plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Конфігурації нативного app-server мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. -Використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі refs моделей `codex/*` -і далі залишаються псевдонімами сумісності для нативного harness-а. +Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі refs моделей `codex/*` +залишаються псевдонімами сумісності для нативного каркаса. -Коли цей режим працює, Codex володіє нативним id треду, поведінкою resume, -Compaction і виконанням app-server. OpenClaw, як і раніше, володіє чатом каналу, -видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та -вибором сеансу. Використовуйте `embeddedHarness.runtime: "codex"` разом із -`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що запуск може -заявити лише шлях app-server Codex. Цей config є лише захистом вибору: -помилки app-server Codex уже напряму завершуються помилкою замість повторної спроби через PI. +Коли цей режим виконується, Codex керує нативним id потоку, поведінкою відновлення, +Compaction і виконанням app-server. OpenClaw усе ще керує чат-каналом, +видимим дзеркалом транскрипту, політикою інструментів, погодженнями, доставкою медіа й +вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із +`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях +Codex app-server може взяти виконання на себе. Ця конфігурація є лише запобіжником вибору: +збої Codex app-server уже й так напряму завершуються помилкою без повторної спроби через PI. -## Вимкнення fallback на PI +## Вимкнення резервного переходу на PI За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, -встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані -harness-и Plugin-ів можуть заявити пару provider/model. Якщо жоден не підходить, OpenClaw -переходить до PI. +встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані плагінні +каркаси можуть заявити про підтримку пари постачальник/модель. Якщо жоден не підходить, +OpenClaw переходить на PI. -Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору harness-а Plugin-а -завершувалася помилкою замість використання PI. Помилки вже вибраних harness-ів Plugin-ів і так -завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору каркаса плагіна +завершувалася помилкою замість використання PI. Збої вже вибраних каркасів плагінів і так завершуються помилкою. Це +не блокує явне `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. -Для вбудованих запусків лише Codex: +Для вбудованих виконань лише з Codex: ```json { @@ -210,9 +209,9 @@ harness-и Plugin-ів можуть заявити пару provider/model. Як } ``` -Якщо ви хочете, щоб будь-який зареєстрований harness Plugin-а міг заявити сумісні моделі, але ніколи -не хочете, щоб OpenClaw непомітно переходив до PI, залиште `runtime: "auto"` і вимкніть -fallback: +Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг заявити про відповідні моделі, але ніколи +не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть +резервний перехід: ```json { @@ -227,7 +226,7 @@ fallback: } ``` -Перевизначення на рівні агента використовують ту саму форму: +Перевизначення для окремого агента використовують ту саму форму: ```json { @@ -252,9 +251,9 @@ fallback: } ``` -`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI через -середовище. +`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований рантайм. Використовуйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через +оточення. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -262,53 +261,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, сеанс завершується рано з помилкою, якщо запитаний harness не -зареєстровано, він не підтримує визначеного provider/model або завершується -помилкою до появи побічних ефектів ходу. Це навмисно для розгортань лише Codex і -для live-тестів, які мають довести, що шлях app-server Codex справді використовується. +Коли резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний каркас не +зареєстровано, він не підтримує визначеного постачальника/модель або завершується помилкою до +появи побічних ефектів ходу. Це навмисно для розгортань лише з Codex і +для live-тестів, які мають довести, що шлях Codex app-server справді використовується. -Цей параметр керує лише вбудованим harness-ом агента. Він не вимикає -маршрутизацію моделей, специфічну для provider, для image, video, music, TTS, PDF або інших типів. +Цей параметр керує лише каркасом вбудованого агента. Він не вимикає маршрутизацію +специфічних для постачальника моделей для зображень, відео, музики, TTS, PDF чи інших. -## Нативні сеанси й дзеркало транскрипту +## Нативні сесії та дзеркало транскрипту -Harness може зберігати нативний id сеансу, id треду або токен resume на боці демона. -Тримайте цю привʼязку явно повʼязаною із сеансом OpenClaw і продовжуйте -дзеркалити видимий користувачу вивід assistant/tool у транскрипт OpenClaw. +Каркас може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. +Явно зберігайте цей зв’язок асоційованим із сесією OpenClaw і продовжуйте +дзеркалити видимий користувачеві вивід асистента/інструментів у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: -- видимої в каналі історії сеансу -- пошуку та індексації транскриптів -- перемикання назад на вбудований harness PI на наступному ході -- узагальненої поведінки `/new`, `/reset` і видалення сеансу +- видимої в каналі історії сесії +- пошуку та індексації транскрипту +- перемикання назад на вбудований каркас PI на наступному ході +- загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваш harness зберігає sidecar-привʼязку, реалізуйте `reset(...)`, щоб OpenClaw міг -очистити її під час скидання повʼязаного сеансу OpenClaw. +Якщо ваш каркас зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг +очистити її, коли пов’язану сесію OpenClaw скинуто. ## Результати інструментів і медіа Core формує список інструментів OpenClaw і передає його в підготовлену спробу. -Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента через -форму результату harness-а замість того, щоб самостійно надсилати медіа в канал. +Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через +форму результату каркаса, а не надсилайте медіа в канал самостійно. -Це зберігає text, image, video, music, TTS, approval і результати -інструментів для повідомлень на тому ж шляху доставки, що й запуски на базі PI. +Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи +інструментів для обміну повідомленнями на тому самому шляху доставки, що й виконання з підтримкою PI. ## Поточні обмеження -- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів досі +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроби/результату все ще містять назви `Pi` для сумісності. -- Установлення сторонніх harness-ів є експериментальним. Віддавайте перевагу provider Plugin-ам, - доки вам не знадобиться нативний runtime сеансів. -- Перемикання harness-ів між ходами підтримується. Не перемикайте harness-и посеред - ходу після того, як уже почалися нативні інструменти, схвалення, текст assistant-а або +- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників, + доки вам не знадобиться нативний рантайм сесії. +- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред + ходу після того, як уже почалися нативні інструменти, погодження, текст асистента або надсилання повідомлень. ## Пов’язане -- [SDK Overview](/uk/plugins/sdk-overview) -- [Runtime Helpers](/uk/plugins/sdk-runtime) -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) -- [Codex Harness](/uk/plugins/codex-harness) -- [Model Providers](/uk/concepts/model-providers) +- [Огляд SDK](/uk/plugins/sdk-overview) +- [Допоміжні засоби рантайму](/uk/plugins/sdk-runtime) +- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) +- [Каркас Codex](/uk/plugins/codex-harness) +- [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 0cdc769cf..89201598d 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -3,36 +3,36 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - Ви використовуєте `api.registerEmbeddedExtensionFactory` - - Ви оновлюєте Plugin до сучасної архітектури плагінів + - Ви оновлюєте Plugin до сучасної архітектури Plugin - Ви підтримуєте зовнішній Plugin OpenClaw sidebarTitle: Migrate to SDK summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-24T20:11:19Z" + generated_at: "2026-04-24T20:32:19Z" model: gpt-5.4 provider: openai - source_hash: 0cd1f130ab3d82113ced47600e259330332d0063e17e8212b9e3120dfc73b0dd + source_hash: fe4a2f78653c1eabd4295cd7ad9cdb7b60995f172b6018650dd8f570f9b47c8d source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів із цілеспрямованими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури Plugin із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система плагінів надавала дві широко відкриті поверхні, які дозволяли плагінам імпортувати все необхідне з однієї точки входу: +Стара система Plugin надавала дві надто широкі поверхні, які дозволяли Plugin імпортувати все, що їм було потрібно, з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб зберегти працездатність старіших плагінів на основі хуків під час розробки нової архітектури плагінів. -- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до допоміжних засобів на боці хоста, таких як вбудований виконавець агентів. -- **`api.registerEmbeddedExtensionFactory(...)`** — хук вбудованого розширення лише для Pi, який міг спостерігати за подіями вбудованого виконавця, такими як `tool_result`. +- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші Plugin на основі хуків продовжували працювати під час створення нової архітектури Plugin. +- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до допоміжних засобів на стороні хоста, таких як вбудований запускальник агентів. +- **`api.registerEmbeddedExtensionFactory(...)`** — хук для вбудованих розширень лише для Pi, який міг спостерігати за подіями вбудованого запускальника, такими як `tool_result`. -Ці поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові Plugin не повинні їх використовувати, а наявні плагіни мають виконати міграцію до того, як наступний мажорний випуск їх прибере. +Тепер ці поверхні **застарілі**. Вони все ще працюють під час виконання, але нові Plugin не повинні їх використовувати, а наявні Plugin слід мігрувати до того, як у наступному мажорному релізі їх буде видалено. -OpenClaw не видаляє і не переосмислює задокументовану поведінку плагінів у тій самій зміні, яка вводить заміну. Зміни контрактів, що ламають сумісність, спочатку мають пройти через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання. +OpenClaw не видаляє й не переосмислює задокументовану поведінку Plugin у тій самій зміні, яка запроваджує заміну. Зміни контракту з порушенням сумісності спершу мають пройти через адаптер сумісності, діагностику, документацію та період застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання. - Шар зворотної сумісності буде видалено в одному з майбутніх мажорних випусків. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. Plugin, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. @@ -40,38 +40,40 @@ OpenClaw не видаляє і не переосмислює задокумен Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних модулів +- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів - **Циклічні залежності** — широкі повторні експорти полегшували створення циклів імпорту -- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми +- **Неочевидна поверхня API** — не було способу визначити, які експорти були стабільними, а які внутрішніми -Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) — це невеликий самодостатній модуль із чітким призначенням і задокументованим контрактом. +Сучасний Plugin SDK вирішує цю проблему: кожен шлях імпорту (`openclaw/plugin-sdk/\`) — це невеликий самодостатній модуль із чітким призначенням і задокументованим контрактом. -Застарілі зручні шви провайдерів для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, допоміжні шви з брендуванням каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями монорепозиторію, а не стабільними контрактами плагінів. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать провайдеру, у власному `api.ts` або `runtime-api.ts` цього плагіна. +Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, допоміжні шви з брендуванням каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями для монорепозиторію, а не стабільними контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать provider, у власному `api.ts` або `runtime-api.ts` цього Plugin. -Поточні приклади вбудованих провайдерів: +Поточні приклади вбудованих provider: -- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби моделей за замовчуванням і конструктори провайдерів realtime у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби онбордингу/конфігурації у власному `api.ts` +- Anthropic зберігає допоміжні засоби потокової передачі, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts` +- OpenAI зберігає конструктори provider, допоміжні засоби для моделей за замовчуванням і конструктори realtime provider у власному `api.ts` +- OpenRouter зберігає конструктор provider і допоміжні засоби онбордингу/конфігурації у власному `api.ts` ## Політика сумісності -Для зовнішніх плагінів робота із сумісністю виконується в такому порядку: +Для зовнішніх Plugin робота із сумісністю виконується в такому порядку: 1. додати новий контракт 2. зберегти стару поведінку, підключивши її через адаптер сумісності -3. вивести діагностику або попередження з назвою старого шляху та заміни -4. покрити тестами обидва шляхи +3. вивести діагностику або попередження, яке вказує старий шлях і заміну +4. покрити тести для обох шляхів 5. задокументувати застарівання та шлях міграції -6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному випуску +6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному релізі -Якщо поле маніфесту все ще приймається, автори плагінів можуть і далі його використовувати, доки документація та діагностика не скажуть інакше. Новий код має віддавати перевагу задокументованій заміні, але наявні плагіни не повинні ламатися у звичайних мінорних випусках. +Якщо поле маніфесту все ще приймається, автори Plugin можуть і далі його використовувати, доки документація й діагностика не скажуть інакше. Новий код має надавати перевагу задокументованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних релізів. -## Як виконати міграцію +## Як мігрувати - - Замініть обробники результатів інструментів Pi-only `api.registerEmbeddedExtensionFactory(...)` на middleware, нейтральне до harness. + + Вбудовані Plugin повинні замінити обробники результатів інструментів лише для Pi через + `api.registerEmbeddedExtensionFactory(...)` на + middleware, нейтральне до harness. ```typescript // Before: Pi-only compatibility hook @@ -89,7 +91,7 @@ OpenClaw не видаляє і не переосмислює задокумен }); ``` - Одночасно оновіть маніфест плагіна: + Одночасно оновіть маніфест Plugin: ```json { @@ -99,29 +101,32 @@ OpenClaw не видаляє і не переосмислює задокумен } ``` - Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності, якому все ще потрібні прямі події вбудованого виконавця Pi. + Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності, якому все ще потрібні прямі події вбудованого запускальника Pi. Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки воно може переписувати вихід інструмента з високим рівнем довіри до того, як модель його побачить. - - Плагіни каналів із підтримкою схвалення тепер надають native-поведінку схвалення через `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту runtime. + + Plugin каналів із підтримкою approval тепер надають нативну поведінку approval через + `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту runtime. Основні зміни: - - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть автентифікацію/доставлення, специфічні для схвалення, зі застарілого підключення `plugin.auth` / `plugin.approvals` на `approvalCapability` - - `ChannelPlugin.approvals` було видалено з публічного контракту плагіна каналу; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу каналу; хуки автентифікації схвалення там більше не зчитуються ядром - - Реєструйте об’єкти runtime, що належать каналу, такі як клієнти, токени або застосунки Bolt, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте сповіщення про переспрямування, що належать плагіну, з native-обробників схвалення; тепер ядро відповідає за сповіщення routed-elsewhere з фактичних результатів доставлення - - Передаючи `channelRuntime` у `createChannelManager(...)`, надавайте справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. + - Замініть `approvalCapability.handler.loadRuntime(...)` на + `approvalCapability.nativeRuntime` + - Перенесіть auth/доставку, специфічні для approval, зі застарілого підключення `plugin.auth` / + `plugin.approvals` на `approvalCapability` + - `ChannelPlugin.approvals` було видалено з публічного контракту Plugin каналу; перенесіть поля delivery/native/render до `approvalCapability` + - `plugin.auth` залишається лише для потоків входу/виходу з каналу; core більше не читає там хуки auth для approval + - Реєструйте об’єкти runtime, що належать каналу, як-от клієнти, токени або застосунки Bolt, через `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте сповіщення про перенаправлення, що належать Plugin, із нативних обробників approval; тепер core відповідає за сповіщення «переспрямовано в інше місце» на основі фактичних результатів доставки + - Під час передавання `channelRuntime` до `createChannelManager(...)` надавайте справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. - Актуальну структуру capability схвалення див. у `/plugins/sdk-channel-plugins`. + Поточну структуру можливостей approval див. у `/plugins/sdk-channel-plugins`. - - Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені Windows-обгортки `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. + + Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows-обгортки `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. ```typescript // Before @@ -130,18 +135,18 @@ OpenClaw не видаляє і не переосмислює задокумен // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Set this only for trusted compatibility callers that intentionally + // Only set this for trusted compatibility callers that intentionally // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Якщо ваш виклик навмисно не покладається на shell fallback, не встановлюйте `allowShellFallback` і натомість обробляйте викинуту помилку. + Якщо ваш виклик не покладається навмисно на резервний перехід через оболонку, не встановлюйте `allowShellFallback`, а натомість обробляйте викинуту помилку. - Знайдіть у своєму плагіні імпорти з будь-якої із застарілих поверхонь: + Знайдіть у своєму Plugin імпорти з будь-якої із застарілих поверхонь: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -150,8 +155,8 @@ OpenClaw не видаляє і не переосмислює задокумен - - Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: ```typescript // Before (deprecated backwards-compatibility layer) @@ -167,7 +172,7 @@ OpenClaw не видаляє і не переосмислює задокумен import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на боці хоста використовуйте впроваджений runtime плагіна замість прямого імпорту: + Для допоміжних засобів на стороні хоста використовуйте ін’єктований runtime Plugin замість прямого імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -178,7 +183,7 @@ OpenClaw не видаляє і не переосмислює задокумен const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується й до інших застарілих допоміжних засобів мосту: + Такий самий шаблон застосовується й до інших застарілих допоміжних засобів bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -203,185 +208,183 @@ OpenClaw не видаляє і не переосмислює задокумен ## Довідник шляхів імпорту - | Шлях імпорту | Призначення | Ключові експорти | + | Шлях імпорту | Призначення | Основні експорти | | --- | --- | --- | | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу Plugin | `definePluginEntry` | | `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цілеспрямовані визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Підказки allowlist, конструктори статусу налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Цільові визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори стану налаштування | + | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для етапу налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/гейтингу дій облікового запису | - | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікового запису | Допоміжні засоби списку облікових записів/дій із ними | + | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби для списку/конфігурації/контролю дій облікових записів | + | `plugin-sdk/account-id` | Допоміжні засоби ідентифікатора облікового запису | `DEFAULT_ACCOUNT_ID`, нормалізація ідентифікатора облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + резервного значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби для списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви прив’язування DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді та індикації набору | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | Примітиви DM-парування | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + індикатора набору | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Допоміжні засоби статусу облікового запису та життєвого циклу потоку чернеток | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернеток | + | `plugin-sdk/channel-lifecycle` | Допоміжні засоби життєвого циклу статусу облікового запису та чернеткового потоку | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки | | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + побудови envelope | | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних відповідей | Спільні допоміжні засоби запису та диспетчеризації | | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні засоби вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегування надсилання та планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу прив’язок потоків та адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор media payload агента для застарілих макетів полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | - | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповідей | + | `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегата надсилання та планування payload | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби payload медіа агента | Конструктор payload медіа агента для застарілих макетів полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | + | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | | `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення плагінів | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, timeout, retry і backoff helper-и | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime Plugin | Допоміжні засоби команд/хуків/http/інтерактивної взаємодії Plugin | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Допоміжні засоби logger/середовища runtime, timeout, retry та backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime Plugin | Допоміжні засоби команд/хуків/http/інтерактивності Plugin | | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра хуків | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні exec helper-и | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | | `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway і патчів статусу каналу | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Клієнт Gateway і допоміжні засоби патчів статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби підказок схвалення | Допоміжні засоби payload схвалення exec/Plugin, capability/profile схвалення, native routing/runtime схвалення | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для схвалення | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта схвалення | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставлення схвалення | Адаптери capability/delivery native approval | - | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway для схвалення | Спільний допоміжний засіб визначення approval gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера схвалення | Полегшені допоміжні засоби завантаження native approval adapter для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника схвалення | Ширші допоміжні засоби runtime обробника схвалення; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей схвалення | Допоміжні засоби прив’язки native approval target/account | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді на схвалення | Допоміжні засоби payload відповіді на exec/Plugin approval | - | `plugin-sdk/channel-runtime-context` | Допоміжні засоби runtime-context каналу | Загальні допоміжні засоби register/get/watch для channel runtime-context | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільною резервною поведінкою, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів approval | Допоміжні засоби payload approval exec/Plugin, можливостей/профілів approval, нативної маршрутизації/runtime approval | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілю/фільтра нативного approval exec | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери нативних можливостей/доставки approval | + | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway для approval | Спільний допоміжний засіб визначення Gateway для approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження адаптера нативного approval для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби runtime обробника approval; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілей/облікових записів нативного approval | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval exec/Plugin | + | `plugin-sdk/channel-runtime-context` | Допоміжні засоби контексту runtime каналу | Загальні допоміжні засоби register/get/watch для контексту runtime каналу | | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів | | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби гейтингу діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби контролю діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, proxy helper-и | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Мапування входів allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Гейтинг команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/command-status` | Рендерери статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби secret input | + | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Допоміжні засоби контролю команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | + | `plugin-sdk/command-status` | Відображувачі стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guards для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний reply runtime | Вхідна диспетчеризація, Heartbeat, планувальник відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Допоміжні засоби фіналізації, диспетчеризації провайдера та міток розмов | + | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Вхідна диспетчеризація, Heartbeat, планувальник відповідей, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Фіналізація, диспетчеризація provider і допоміжні засоби міток розмов | | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби чанків відповіді | Допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні засоби чанків відповідей | Допоміжні засоби чанкінгу тексту/markdown | | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори підсумків статусу каналу/облікового запису, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілі | Спільні допоміжні засоби target resolver | + | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключів сесій | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації ключів сесій | + | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори підсумку статусу каналу/облікового запису, значення стану runtime за замовчуванням, допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілі | Спільні допоміжні засоби визначення цілі | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягання рядкових URL з input-ів, подібних до request | - | `plugin-sdk/run-command` | Допоміжні засоби команд із таймером | Виконавець команд із таймером із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування tool payload | Витягання нормалізованих payload із об’єктів результатів інструментів | - | `plugin-sdk/tool-send` | Витягування tool send | Витягання канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягання рядкових URL з вхідних даних, подібних до запиту | + | `plugin-sdk/run-command` | Допоміжні засоби команд із timeout | Виконавець команд із timeout і нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Читачі параметрів | Загальні читачі параметрів інструментів/CLI | + | `plugin-sdk/tool-payload` | Витягання payload інструмента | Витягання нормалізованих payload з об’єктів результатів інструментів | + | `plugin-sdk/tool-send` | Витягання надсилання інструмента | Витягання канонічних полів цілі надсилання з аргументів інструмента | | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби логування | Logger підсистеми та допоміжні засоби редагування секретів | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режимів markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи відповідей повідомлень | Типи reply payload | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted провайдера | Допоміжні засоби виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/self-hosted-provider-setup` | Цілеспрямовані допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime провайдера | Допоміжні засоби визначення API-ключа runtime | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth провайдера | Стандартний конструктор результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору провайдера | Вибір налаштованого або автоматичного провайдера та об’єднання необробленої конфігурації провайдера | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars auth провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повторення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Загальні допоміжні засоби HTTP/endpoint capability провайдера, включно з допоміжними засобами multipart form для транскрибування аудіо | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешування провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search провайдера | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення enable Plugin | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешування/runtime провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні засоби compat для tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також xAI compat helper-и, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби usage провайдера | - | `plugin-sdk/provider-stream` | Допоміжні засоби wrapper-ів потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи wrapper-ів потоку та спільні допоміжні засоби wrapper-ів Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Допоміжні засоби native transport провайдера, такі як guarded fetch, трансформації транспортних повідомлень і потоки подій writable transport | - | `plugin-sdk/keyed-async-queue` | Впорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби fetch/transform/store для медіа, а також конструктори media payload | + | `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистем і редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць | + | `plugin-sdk/reply-payload` | Типи payload відповідей | Типи payload відповідей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | Допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime provider | Допоміжні засоби визначення API-ключа runtime | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа provider | Допоміжні засоби онбордингу/запису профілю API-ключа | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth provider | Стандартний конструктор результату auth OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору provider | Вибір налаштованого або автоматичного provider і злиття сирої конфігурації provider | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби змінних середовища provider | Допоміжні засоби пошуку змінних середовища auth provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/повторного відтворення provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик replay, допоміжні засоби endpoint provider і нормалізації ідентифікаторів моделей | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі онбордингу provider | Допоміжні засоби конфігурації онбордингу | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Загальні допоміжні засоби HTTP/можливостей endpoint provider, включно з допоміжними засобами multipart form для аудіотранскрипції | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/кешу web-fetch provider | + | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації вебпошуку provider | Вузькі допоміжні засоби конфігурації/облікових даних вебпошуку для provider, яким не потрібне підключення ввімкнення Plugin | + | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту вебпошуку provider | Вузькі допоміжні засоби контракту конфігурації/облікових даних вебпошуку, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби вебпошуку provider | Допоміжні засоби реєстрації/кешу/runtime вебпошуку provider | + | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні засоби використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання provider | + | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту provider | Нативні допоміжні засоби транспорту provider, як-от guarded fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | + | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/зберігання медіа, а також конструктори payload медіа | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдерів media understanding, а також provider-facing helper-и для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення тексту, видимого асистенту, helper-и рендерингу/chunking/таблиць markdown, helper-и редагування секретів, helper-и тегів директив, safe-text utilities та пов’язані helper-и тексту/логування | - | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи провайдерів мовлення, а також provider-facing helper-и директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдерів мовлення, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрибування в реальному часі | Типи провайдерів, helper-и реєстру та спільний допоміжний засіб сесій WebSocket | - | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи провайдерів, helper-и реєстру/визначення та helper-и bridge sessions | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, helper-и failover, auth і реєстру | - | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, helper-и failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, helper-и failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/зменшення payload інтерактивних відповідей | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | + | `plugin-sdk/media-understanding` | Допоміжні засоби розуміння медіа | Типи provider для розуміння медіа, а також експорти допоміжних засобів зображень/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, допоміжні засоби рендерингу/chunking/table markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування | + | `plugin-sdk/text-chunking` | Допоміжні засоби чанкінгу тексту | Допоміжний засіб чанкінгу вихідного тексту | + | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи provider мовлення, а також допоміжні засоби директив, реєстру та валідації для provider | + | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи provider мовлення, реєстр, директиви, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в realtime | Типи provider, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | + | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в realtime | Типи provider, допоміжні засоби реєстру/визначення та допоміжні засоби bridge-сесій | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, auth і допоміжні засоби реєстру | + | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи provider/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи provider/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей | + | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви config-schema каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули channel Plugin | + | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude Plugin каналу | | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до групи | Спільні допоміжні засоби визначення group-access | - | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні helper-и auth/guard для direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби розширення | Примітиви helper-ів passive-channel/status і ambient proxy | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Реєстр цілей Webhook і helper-и встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляху Webhook | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для користувачів Plugin SDK | - | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня helper-ів менеджера memory/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія memory | Фасад runtime індексування/пошуку memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій host memory | Експорти базового рушія host memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings для host memory | Контракти embeddings memory, доступ до реєстру, локальний провайдер і загальні helper-и batch/remote; конкретні віддалені провайдери містяться у плагінах-власниках | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD для host memory | Експорти рушія QMD для host memory | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища для host memory | Експорти рушія сховища для host memory | - | `plugin-sdk/memory-core-host-multimodal` | Багатомодальні допоміжні засоби host memory | Багатомодальні допоміжні засоби host memory | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів host memory | Допоміжні засоби запитів host memory | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів host memory | Допоміжні засоби секретів host memory | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій host memory | Допоміжні засоби журналу подій host memory | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу host memory | Допоміжні засоби статусу host memory | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime для host memory | Допоміжні засоби CLI runtime для host memory | - | `plugin-sdk/memory-core-host-runtime-core` | Core runtime для host memory | Допоміжні засоби core runtime для host memory | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime для host memory | Допоміжні засоби файлів/runtime для host memory | - | `plugin-sdk/memory-host-core` | Псевдонім core runtime для host memory | Нейтральний до вендора псевдонім для helper-ів core runtime host memory | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій host memory | Нейтральний до вендора псевдонім для helper-ів журналу подій host memory | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime для host memory | Нейтральний до вендора псевдонім для helper-ів файлів/runtime host memory | - | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні helper-и керованого markdown для плагінів, суміжних із memory | + | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо доступу до груп | + | `plugin-sdk/direct-dm` | Допоміжні засоби прямих DM | Спільні допоміжні засоби auth/guard для прямих DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів пасивного каналу/статусу та ambient proxy | + | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook та встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддаленого/локального медіа | + | `plugin-sdk/zod` | Повторний експорт zod | Повторно експортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів менеджера/config/файлів/CLI пам’яті | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексу/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і загальні допоміжні засоби batch/remote; конкретні remote provider містяться у Plugin, яким вони належать | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби мультимодального хоста пам’яті | Допоміжні засоби мультимодального хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні засоби core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю | | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory | - | `plugin-sdk/memory-host-status` | Псевдонім статусу host memory | Нейтральний до вендора псевдонім для helper-ів статусу host memory | - | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня helper-ів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mock-об’єкти | + | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | + | `plugin-sdk/testing` | Тестові утиліти | Допоміжні засоби тестування та mocks | -Ця таблиця навмисно містить поширену підмножину для міграції, а не всю -поверхню SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною поверхнею SDK. Повний список із понад 200 точок входу міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще включає деякі допоміжні шви для вбудованих плагінів, такі як +Цей список усе ще містить деякі шви допоміжних засобів вбудованих Plugin, як-от `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для -підтримки вбудованих плагінів і сумісності, але навмисно -не включені до таблиці поширеної міграції та не є рекомендованою ціллю для -нового коду Plugin. +`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для +підтримки та сумісності вбудованих Plugin, але навмисно не включені до +поширеної таблиці міграції та не є рекомендованою ціллю для нового коду Plugin. -Те саме правило застосовується до інших сімейств вбудованих helper-ів, таких як: +Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як: -- helper-и підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- допоміжні засоби підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих helper-ів/плагінів, такі як `plugin-sdk/googlechat`, +- поверхні вбудованих допоміжних засобів/Plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -390,28 +393,28 @@ OpenClaw не видаляє і не переосмислює задокумен `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню helper-ів токена: +`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токена: `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти експорт, -перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. +Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти експорт, +перевірте джерело в `src/plugin-sdk/` або запитайте в Discord. ## Активні застарівання -Вужчі застарівання, які застосовуються до всього Plugin SDK, контракту провайдера, -поверхні runtime і маніфесту. Кожне з них і далі працює сьогодні, але буде видалене -в одному з майбутніх мажорних випусків. Запис під кожним елементом зіставляє старий API -з його канонічною заміною. +Вужчі застарівання, які застосовуються в усьому Plugin SDK, контракті provider, +поверхні runtime і маніфесті. Кожен із них іще працює сьогодні, але буде видалений +у майбутньому мажорному релізі. Запис під кожним елементом зіставляє старий API з його +канонічною заміною. - + **Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`. **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі - експорти — лише імпорт із вужчого підшляху. `command-auth` - повторно експортує їх як compat stub-и. + експорти — лише імпортовані з вужчого підшляху. `command-auth` + повторно експортує їх як compat-заглушки. ```typescript // Before @@ -423,97 +426,96 @@ OpenClaw не видаляє і не переосмислює задокумен - + **Старе**: `resolveInboundMentionRequirement({ facts, policy })` і `shouldDropInboundForMention(...)` з `openclaw/plugin-sdk/channel-inbound` або `openclaw/plugin-sdk/channel-mention-gating`. **Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає - один об’єкт рішення замість двох розділених викликів. + єдиний об’єкт рішення замість двох розділених викликів. - Нижчі плагіни каналів (Slack, Discord, Matrix, Microsoft Teams) уже - перейшли. + Низхідні Plugin каналів (Slack, Discord, Matrix, MS Teams) уже + перейшли на це. - - `openclaw/plugin-sdk/channel-runtime` — це compat shim для старіших - плагінів каналів. Не імпортуйте його в новому коді; використовуйте + + `openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших + Plugin каналів. Не імпортуйте його в новому коді; використовуйте `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів runtime. - helper-и `channelActions*` у `openclaw/plugin-sdk/channel-actions` застаріли - разом із сирими експортами каналу "actions". Натомість надавайте capability - через семантичну поверхню `presentation` — плагіни каналів декларують, що - саме вони рендерять (картки, кнопки, select), а не те, які сирі назви - actions вони приймають. + Допоміжні засоби `channelActions*` у `openclaw/plugin-sdk/channel-actions` застаріли + разом із сирими експортами дій каналу. Натомість надавайте можливості через + семантичну поверхню `presentation` — Plugin каналів оголошують, що саме вони рендерять + (картки, кнопки, списки вибору), а не які сирі назви дій вони приймають. - + **Старе**: фабрика `tool()` з `openclaw/plugin-sdk/provider-web-search`. - **Нове**: реалізуйте `createTool(...)` безпосередньо в плагіні провайдера. - OpenClaw більше не потребує helper-а SDK для реєстрації обгортки tool. + **Нове**: реалізуйте `createTool(...)` безпосередньо в Plugin provider. + OpenClaw більше не потрібен допоміжний засіб SDK для реєстрації обгортки інструмента. - + **Старе**: `formatInboundEnvelope(...)` (і - `ChannelMessageForAgent.channelEnvelope`) для побудови плоского текстового prompt - envelope із вхідних повідомлень каналу. + `ChannelMessageForAgent.channelEnvelope`) для побудови плоского текстового prompt-envelope + із вхідних повідомлень каналу. - **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. - Плагіни каналів додають метадані маршрутизації (потік, тему, reply-to, реакції) як - типізовані поля, а не конкатенують їх у рядок prompt. helper - `formatAgentEnvelope(...)` усе ще підтримується для синтезованих envelope, - видимих асистенту, але вхідні текстові envelope поступово виводяться з використання. + **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Plugin + каналів прикріплюють метадані маршрутизації (потік, тему, reply-to, реакції) як + типізовані поля замість конкатенації їх у рядок prompt. Допоміжний засіб + `formatAgentEnvelope(...)` і далі підтримується для синтезованих envelope, + орієнтованих на асистента, але вхідні текстові envelope поступово виводяться з ужитку. Зачеплені області: `inbound_claim`, `message_received` і будь-який користувацький Plugin каналу, який постобробляв текст `channelEnvelope`. - + Чотири псевдоніми типів виявлення тепер є тонкими обгортками над типами - епохи каталогу: + ери каталогу: - | Старий псевдонім | Новий тип | - | ------------------------- | ------------------------ | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | Старий псевдонім | Новий тип | + | --------------------------- | ------------------------- | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext` | `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - Плюс застарілий статичний набір `ProviderCapabilities` — плагіни провайдерів - мають прикріплювати факти capability через контракт runtime провайдера, + Плюс застарілий статичний набір `ProviderCapabilities` — Plugin provider + повинні прикріплювати факти можливостей через контракт runtime provider, а не через статичний об’єкт. - + **Старе** (три окремі хуки в `ProviderThinkingPolicy`): `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і `resolveDefaultThinkingLevel(ctx)`. - **Нове**: єдиний `resolveThinkingProfile(ctx)`, який повертає - `ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і - ранжованим списком рівнів. OpenClaw автоматично понижує застарілі збережені - значення за рангом профілю. + **Нове**: один `resolveThinkingProfile(ctx)`, який повертає + `ProviderThinkingProfile` з канонічним `id`, необов’язковим `label` і + ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені значення + за рангом профілю. - Реалізуйте один хук замість трьох. Застарілі хуки продовжують працювати - протягом вікна застарівання, але не комбінуються з результатом профілю. + Реалізуйте один хук замість трьох. Застарілі хуки продовжують працювати впродовж + вікна застарівання, але не комбінуються з результатом профілю. - + **Старе**: реалізація `resolveExternalOAuthProfiles(...)` без - оголошення провайдера в маніфесті Plugin. + оголошення provider у маніфесті Plugin. **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті Plugin - **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях "auth - fallback" виводить попередження під час runtime і буде видалений. + **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях + «резервного auth» видає попередження під час виконання й буде видалений. ```json { @@ -525,53 +527,53 @@ OpenClaw не видаляє і не переосмислює задокумен - + **Старе** поле маніфесту: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. **Нове**: віддзеркальте той самий пошук env vars у `setup.providers[].envVars` в маніфесті. Це об’єднує метадані env налаштування/статусу в одному - місці та дає змогу уникнути запуску runtime плагіна лише для відповіді на - пошук env vars. + місці й дозволяє уникнути запуску runtime Plugin лише для того, щоб відповісти на + запити щодо env vars. - `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності + `providerAuthEnvVars` і далі підтримується через адаптер сумісності до завершення вікна застарівання. - + **Старе**: три окремі виклики — `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`. - **Нове**: один виклик в API memory-state — + **Нове**: один виклик у API стану пам’яті — `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. - Ті самі слоти, один виклик реєстрації. Додаткові helper-и memory + Ті самі слоти, один виклик реєстрації. Адитивні допоміжні засоби пам’яті (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, - `registerMemoryEmbeddingProvider`) не зачеплено. + `registerMemoryEmbeddingProvider`) це не зачіпає. - - Два застарілі псевдоніми типів усе ще експортуються з `src/plugins/runtime/types.ts`: + + Два застарілі псевдоніми типів і далі експортуються з `src/plugins/runtime/types.ts`: - | Старий | Новий | + | Старе | Нове | | ---------------------------- | ------------------------------- | | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | Метод runtime `readSession` застарів на користь - `getSessionMessages`. Сигнатура та сама; старий метод викликає + `getSessionMessages`. Та сама сигнатура; старий метод викликає новий. - **Старе**: `runtime.tasks.flow` (однина) повертав живий accessor task-flow. + **Старе**: `runtime.tasks.flow` (в однині) повертав засіб доступу до live TaskFlow. - **Нове**: `runtime.tasks.flows` (множина) повертає DTO-орієнтований доступ до TaskFlow, - який є безпечним для імпорту та не вимагає завантаження повного runtime завдань. + **Нове**: `runtime.tasks.flows` (у множині) повертає доступ до TaskFlow на основі DTO, + який безпечний для імпорту й не потребує завантаження повного runtime завдань. ```typescript // Before @@ -582,17 +584,17 @@ OpenClaw не видаляє і не переосмислює задокумен - - Розглянуто вище в розділі «Як виконати міграцію → Перенесіть розширення Pi для результатів інструментів на - middleware». Для повноти: шлях Pi-only + + Розглянуто вище в розділі «Як мігрувати → Мігруйте розширення результатів інструментів Pi на + middleware». Тут наведено для повноти: шлях лише для Pi `api.registerEmbeddedExtensionFactory(...)` застарів на користь `api.registerAgentToolResultMiddleware(...)` з явним списком harness у `contracts.agentToolResultMiddleware`. - + `OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є - однорядковим псевдонімом для `OpenClawConfig`. Віддавайте перевагу канонічній назві. + однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу канонічній назві. ```typescript // Before @@ -605,39 +607,39 @@ OpenClaw не видаляє і не переосмислює задокумен -Застарівання на рівні розширень (усередині вбудованих плагінів каналів/провайдерів у -`extensions/`) відстежуються у їхніх власних barrel-файлах `api.ts` і `runtime-api.ts`. -Вони не впливають на контракти сторонніх плагінів і тут не перелічені. Якщо ви -безпосередньо використовуєте локальний barrel вбудованого плагіна, прочитайте -коментарі щодо застарівання в цьому barrel-файлі перед оновленням. +Застарівання на рівні extension (усередині вбудованих Plugin каналів/provider у +`extensions/`) відстежуються у власних barrel-файлах `api.ts` і `runtime-api.ts`. +Вони не впливають на контракти сторонніх Plugin і тут не перелічені. +Якщо ви напряму споживаєте локальний barrel вбудованого Plugin, прочитайте +коментарі щодо застарівання в цьому barrel перед оновленням. ## Часова шкала видалення | Коли | Що відбувається | | ---------------------- | ---------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні виводять попередження під час runtime | -| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; плагіни, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні виводять попередження під час виконання | +| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; Plugin, які досі їх використовують, перестануть працювати | -Усі core-плагіни вже перенесено. Зовнішнім плагінам слід виконати міграцію -до наступного мажорного випуску. +Усі core Plugin уже мігровано. Зовнішнім Plugin слід виконати +міграцію до наступного мажорного релізу. ## Тимчасове приглушення попереджень -Установіть ці змінні середовища під час роботи над міграцією: +Установіть ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий аварійний обхід, а не постійне рішення. +Це тимчасовий обхідний механізм, а не постійне рішення. ## Пов’язане - [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту підшляхів -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів -- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів -- [Внутрішня будова Plugin](/uk/plugins/architecture) — поглиблений розбір архітектури +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів +- [Plugin каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin каналів +- [Plugin provider](/uk/plugins/sdk-provider-plugins) — створення Plugin provider +- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибоке занурення в архітектуру - [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 57873a6f8..a0c29b167 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - - Вам потрібно знати, з якого підшляху SDK імпортувати - - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Потрібно знати, з якого підшляху SDK імпортувати + - Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK -title: Огляд SDK Plugin-ів +summary: Карта імпорту, довідник з API реєстрації та архітектура SDK +title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-24T19:52:51Z" + generated_at: "2026-04-24T20:32:17Z" model: gpt-5.4 provider: openai - source_hash: 791b22f4753094ab1e0d26fb4d471cd400e9a34be699736fb96646d9e620d3cb + source_hash: 7b7b69a59c39d3abd5c70a1420e2f43da0470f66d283d76f069b0e77a5bf1551 source_path: plugins/sdk-overview.md workflow: 15 --- -SDK Plugin-ів — це типізований контракт між Plugin-ами та ядром. Ця сторінка — +Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — довідник про **що імпортувати** і **що можна реєструвати**. Шукаєте натомість практичний посібник? -- Перший Plugin? Почніть із [Створення Plugin-ів](/uk/plugins/building-plugins). -- Plugin каналу? Див. [Plugin-и каналів](/uk/plugins/sdk-channel-plugins). -- Plugin провайдера? Див. [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins). -- Plugin інструмента або hook життєвого циклу? Див. [Hook-и Plugin-а](/uk/plugins/hooks). +- Перший плагін? Почніть із [Створення плагінів](/uk/plugins/building-plugins). +- Плагін каналу? Дивіться [Плагіни каналів](/uk/plugins/sdk-channel-plugins). +- Плагін провайдера? Дивіться [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins). +- Плагін інструмента або хука життєвого циклу? Дивіться [Хуки плагінів](/uk/plugins/hooks). ## Угода щодо імпорту @@ -37,112 +37,113 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і -запобігає проблемам із циклічними залежностями. Для специфічних для каналу допоміжних засобів точки входу/збирання -віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для -ширшої umbrella-поверхні та спільних допоміжних засобів, таких як +запобігає проблемам із циклічними залежностями. Для специфічних для каналу +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +ширшої поверхні-парасольки та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. - Не імпортуйте з брендованих зручних seam-ів провайдерів або каналів (наприклад + Не імпортуйте branded convenience seams для провайдерів або каналів (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Bundled Plugin-и поєднують загальні підшляхи SDK у власних barrel-файлах `api.ts` / - `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні barrel-файли Plugin-ів, - або додавати вузький загальний контракт SDK, коли потреба справді є - міжканальною. + Вбудовані плагіни поєднують загальні підшляхи SDK у власних barrel-файлах `api.ts` / + `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для плагіна + barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді + є міжканальною. -Невеликий набір helper seam-ів bundled Plugin-ів (`plugin-sdk/feishu`, +Невеликий набір helper seams для вбудованих плагінів (`plugin-sdk/feishu`, `plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в -згенерованій карті експортів. Вони існують лише для підтримки bundled Plugin-ів і -не рекомендовані як шляхи імпорту для нових сторонніх Plugin-ів. +згенерованій карті експортів. Вони існують лише для супроводу вбудованих плагінів і +не рекомендуються як шляхи імпорту для нових сторонніх плагінів. ## Довідник підшляхів -SDK Plugin-ів надається як набір вузьких підшляхів, згрупованих за напрямами (Plugin -entry, channel, provider, auth, runtime, capability, memory і зарезервовані -helper-и bundled Plugin-ів). Повний каталог — зі групуванням і посиланнями — див. у -[Підшляхи SDK Plugin-ів](/uk/plugins/sdk-subpaths). +Plugin SDK доступний як набір вузьких підшляхів, згрупованих за областями (entry +плагіна, канал, провайдер, auth, runtime, capability, memory і зарезервовані +helper-модулі для вбудованих плагінів). Повний каталог — згрупований і з посиланнями — дивіться в +[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). -Згенерований список із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`. +Згенерований список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` із такими методами: ### Реєстрація можливостей | Метод | Що він реєструє | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | +| ------------------------------------------------ | ----------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | | `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний CLI-бекенд inference | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Двосторонні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Web search | +| `api.registerCliBackend(...)` | Локальний backend inference для CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез мовлення / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти й команди +### Інструменти та команди | Метод | Що він реєструє | -| ------------------------------- | --------------------------------------------- | +| ------------------------------- | ------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Кастомна команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура | Метод | Що він реєструє | -| ----------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook події | -| `api.registerHttpRoute(params)` | HTTP-кінцева точка Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerGatewayDiscoveryService(service)` | Рекламування виявлення локального Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструмента harness | -| `api.registerEmbeddedExtensionFactory(factory)` | Застаріла фабрика розширень Pi | -| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція prompt, суміжна з пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| ----------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук події | +| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerGatewayDiscoveryService(service)` | Рекламування локального виявлення Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструментів harness | +| `api.registerEmbeddedExtensionFactory(factory)` | Застаріла фабрика розширень PI | +| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ промпта, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | - Зарезервовані простори назв адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити - вужчу область методу Gateway. Для методів, що належать Plugin-у, віддавайте перевагу - префіксам, специфічним для Plugin-а. + Зарезервовані простори назв адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити + вужчу область дії для методу gateway. Для методів, що належать плагіну, віддавайте перевагу + префіксам, специфічним для плагіна. - - Використовуйте `api.registerAgentToolResultMiddleware(...)`, коли Plugin-у потрібно - переписати результат інструмента після виконання і до того, як harness передасть цей - результат назад у модель. Це нейтральний до harness seam для асинхронних - редукторів виводу, таких як tokenjuice. + + Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли + їм потрібно переписати результат інструмента після виконання і до того, як harness + передасть цей результат назад у модель. Це довірений, нейтральний щодо harness + seam для асинхронних редукторів виводу, таких як tokenjuice. -Plugin-и мають оголошувати `contracts.agentToolResultMiddleware` для кожного цільового -harness, наприклад `["pi", "codex-app-server"]`. Для роботи, якій не потрібен час результату інструмента до моделі, -залишайте звичайні hook-и Plugin-ів OpenClaw. +Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного +цільового harness, наприклад `["pi", "codex-app-server"]`. Зовнішні плагіни +не можуть реєструвати це middleware; для роботи, якій не потрібен час обробки +результату інструмента до моделі, залишайте звичайні хуки плагінів OpenClaw. `api.registerEmbeddedExtensionFactory(...)` є застарілим. Він залишається - сумісним seam для bundled Plugin-ів, яким усе ще потрібні прямі події - вбудованого виконання Pi. Нові трансформації результатів інструментів мають - натомість використовувати `api.registerAgentToolResultMiddleware(...)`. + сумісним seam для вбудованих плагінів, яким усе ще потрібні прямі події + embedded-runner Pi. Нові перетворення результатів інструментів натомість мають використовувати + `api.registerAgentToolResultMiddleware(...)`. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дозволяє Plugin-у рекламувати активний +`api.registerGatewayDiscoveryService(...)` дозволяє плагіну рекламувати активний Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає сервіс -під час запуску Gateway, коли локальне виявлення ввімкнено, передає поточні -порти Gateway і не секретні дані-підказки TXT, а також викликає повернений -обробник `stop` під час завершення роботи Gateway. +під час запуску Gateway, коли локальне виявлення ввімкнене, передає поточні +порти Gateway і несеκретні TXT-підказки, а під час завершення роботи Gateway +викликає повернений обробник `stop`. ```typescript api.registerGatewayDiscoveryService({ @@ -158,20 +159,21 @@ api.registerGatewayDiscoveryService({ }); ``` -Plugin-и виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або -автентифікацію. Виявлення — це підказка для маршрутизації; довіра все ще належить автентифікації Gateway і pinning TLS. +Плагіни виявлення Gateway не повинні розглядати рекламовані значення TXT як секрети або +автентифікацію. Виявлення — це підказка для маршрутизації; довірою як і раніше керують +автентифікація Gateway і pinning TLS. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд часу парсингу, які використовуються для довідки кореневого CLI, - маршрутизації та лінивої реєстрації CLI Plugin-а +- `commands`: явні корені команд, що належать реєстратору +- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для довідки root CLI, + маршрутизації та лінивої реєстрації CLI плагіна -Якщо ви хочете, щоб команда Plugin-а залишалася ліниво завантажуваною в звичайному шляху кореневого CLI, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається цим -registrar. +Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному шляху root CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається +цим реєстратором. ```typescript api.registerCli( @@ -183,7 +185,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -191,130 +193,131 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореневого CLI. -Цей сумісний eager-шлях усе ще підтримується, але він не встановлює -placeholder-и на основі дескрипторів для лінивого завантаження під час парсингу. +Використовуйте лише `commands`, тільки якщо вам не потрібна лінива реєстрація root CLI. +Цей eager-сумісний шлях усе ще підтримується, але не встановлює +плейсхолдери на основі дескрипторів для лінивого завантаження під час парсингу. -### Реєстрація CLI-бекенда +### Реєстрація backend CLI -`api.registerCliBackend(...)` дозволяє Plugin-у володіти типовою конфігурацією для локального -AI CLI-бекенда, такого як `codex-cli`. +`api.registerCliBackend(...)` дозволяє плагіну володіти конфігурацією за замовчуванням для локального +backend AI CLI, такого як `codex-cli`. -- `id` бекенда стає префіксом провайдера в посиланнях на моделі на кшталт `codex-cli/gpt-5`. -- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має перевагу. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - типового значення Plugin-а перед запуском CLI. -- Використовуйте `normalizeConfig`, коли бекенду потрібні сумісні переписування після об’єднання - (наприклад, нормалізація старих форм прапорців). +- `id` backend стає префіксом провайдера в посиланнях на моделі, таких як `codex-cli/gpt-5`. +- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх + стандартної конфігурації плагіна перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття + (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти | Метод | Що він реєструє | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг адаптувати доповнення prompt. | -| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Генератор секції prompt для пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до промпта. | +| `api.registerMemoryCapability(capability)` | Єдина можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор розділу промпта пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding-ів пам’яті +### Адаптери embedding для пам’яті | Метод | Що він реєструє | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding-ів пам’яті для активного Plugin-а | +| ---------------------------------------------- | -------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного плагіна | -- `registerMemoryCapability` — це бажаний API ексклюзивного Plugin-а пам’яті. +- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті. - `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб допоміжні Plugin-и могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного макета - конкретного Plugin-а пам’яті. + щоб плагіни-супутники могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури + конкретного плагіна пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні із застарілими версіями API ексклюзивного Plugin-а пам’яті. -- `registerMemoryEmbeddingProvider` дозволяє активному Plugin-у пам’яті реєструвати один - або кілька id адаптерів embedding-ів (наприклад, `openai`, `gemini` або кастомний id, визначений Plugin-ом). -- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих id - адаптерів. + `registerMemoryRuntime` — це сумісні зі старими версіями API ексклюзивного плагіна пам’яті. +- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті реєструвати один + або більше ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або + користувацький ідентифікатор, визначений плагіном). +- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими + ідентифікаторами адаптерів. ### Події та життєвий цикл -| Метод | Що він робить | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | +| Метод | Що він робить | +| -------------------------------------------- | --------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | -Див. [Hook-и Plugin-а](/uk/plugins/hooks), щоб переглянути приклади, поширені назви hook-ів і +Дивіться [Хуки плагінів](/uk/plugins/hooks), щоб переглянути приклади, поширені назви хуків і семантику guard. -### Семантика рішень hook-ів +### Семантика рішень для хуків -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. - `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. - `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перебирає на себе dispatch, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. - `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до `metadata`, специфічних для каналу. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні hook-и `gateway:startup`. +- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідного thread/topic. `metadata` залишайте для специфічних для каналу додаткових даних. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж повертатися до специфічного для каналу `metadata`. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні хуки `gateway:startup`. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------- | -| `api.id` | `string` | id Plugin-а | -| `api.name` | `string` | Ім’я для відображення | -| `api.version` | `string?` | Версія Plugin-а (необов’язково) | -| `api.description` | `string?` | Опис Plugin-а (необов’язково) | -| `api.source` | `string` | Шлях до джерела Plugin-а | -| `api.rootDir` | `string?` | Кореневий каталог Plugin-а (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Конфігурація Plugin-а з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного входу | -| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin-а | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Ідентифікатор плагіна | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний внутрішній знімок runtime, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, із `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | ## Угода щодо внутрішніх модулів -Усередині вашого Plugin-а використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: -```text +``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні експорти середовища виконання - index.ts # Точка входу Plugin-а - setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) + runtime-api.ts # Експорти runtime лише для внутрішнього використання + index.ts # Точка входу плагіна + setup-entry.ts # Легка точка входу лише для setup (необов’язково) ``` - Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` - у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні bundled Plugin-ів, завантажених через facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні файли входу), віддають перевагу -активному знімку конфігурації середовища виконання, коли OpenClaw уже працює. Якщо знімок середовища виконання -ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску. +Публічні поверхні вбудованих плагінів, завантажених через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу +активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime +ще не існує, вони повертаються до визначеного файлу конфігурації на диску. -Plugin-и провайдерів можуть надавати вузький barrel локального контракту Plugin-а, коли +Плагіни провайдерів можуть надавати вузький локальний для плагіна контрактний barrel, коли допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. -Bundled приклади: +Приклади вбудованих плагінів: -- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude - з beta-header і допоміжними засобами потоку `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує конструктори провайдерів, - допоміжні засоби моделей за замовчуванням і конструктори провайдерів реального часу. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує конструктор провайдера - плюс допоміжні засоби onboarding/конфігурації. +- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для заголовка бета-функцій Claude + та допоміжних засобів потоків `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує builder-об’єкти провайдера, + допоміжні засоби моделей за замовчуванням і builder-об’єкти провайдерів realtime. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера + разом із допоміжними засобами onboarding/config. Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, - наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливість, замість того щоб жорстко пов’язувати два Plugin-и. + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою. ## Пов’язане @@ -323,11 +326,11 @@ Bundled приклади: Параметри `definePluginEntry` і `defineChannelPluginEntry`. - + Повний довідник простору назв `api.runtime`. - - Пакування, маніфести й схеми конфігурації. + + Пакування, маніфести та схеми конфігурації. Утиліти тестування та правила lint. @@ -335,7 +338,7 @@ Bundled приклади: Міграція із застарілих поверхонь. - - Детальна архітектура та модель можливостей. + + Поглиблена архітектура та модель можливостей. diff --git a/docs/uk/providers/comfy.md b/docs/uk/providers/comfy.md index d2c7ce265..5692fc270 100644 --- a/docs/uk/providers/comfy.md +++ b/docs/uk/providers/comfy.md @@ -1,67 +1,69 @@ --- read_when: - Ви хочете використовувати локальні робочі процеси ComfyUI з OpenClaw - - Ви хочете використовувати Comfy Cloud із робочими процесами зображень, відео або музики + - Ви хочете використовувати Comfy Cloud із робочими процесами для зображень, відео або музики - Вам потрібні ключі конфігурації вбудованого Plugin comfy -summary: Налаштування генерації зображень, відео та музики через робочий процес ComfyUI в OpenClaw +summary: Налаштування робочого процесу ComfyUI для генерації зображень, відео та музики в OpenClaw title: ComfyUI x-i18n: - generated_at: "2026-04-24T03:47:59Z" + generated_at: "2026-04-24T20:32:20Z" model: gpt-5.4 provider: openai - source_hash: d8b39c49df3ad23018372b481681ce89deac3271da5dbdf94580712ace7fef7f + source_hash: 41dda4be24d5b2c283fa499a345cf9f38747ec19b4010163ceffd998307ca086 source_path: providers/comfy.md workflow: 15 --- -OpenClaw постачається з вбудованим Plugin `comfy` для запусків ComfyUI на основі workflow. Plugin повністю керується workflow, тому OpenClaw не намагається зіставляти загальні `size`, `aspectRatio`, `resolution`, `durationSeconds` або елементи керування у стилі TTS з вашим графом. +OpenClaw постачається з вбудованим Plugin `comfy` для запусків ComfyUI на основі робочих процесів. Plugin повністю керується робочими процесами, тому OpenClaw не намагається зіставляти загальні `size`, `aspectRatio`, `resolution`, `durationSeconds` або елементи керування в стилі TTS з вашим графом. -| Property | Detail | -| --------------- | -------------------------------------------------------------------------------- | -| Provider | `comfy` | -| Models | `comfy/workflow` | -| Shared surfaces | `image_generate`, `video_generate`, `music_generate` | +| Property | Detail | +| --------------- | -------------------------------------------------------------------------------------- | +| Provider | `comfy` | +| Models | `comfy/workflow` | +| Shared surfaces | `image_generate`, `video_generate`, `music_generate` | | Auth | Немає для локального ComfyUI; `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для Comfy Cloud | -| API | ComfyUI `/prompt` / `/history` / `/view` і Comfy Cloud `/api/*` | +| API | ComfyUI `/prompt` / `/history` / `/view` та Comfy Cloud `/api/*` | ## Що підтримується -- Генерація зображень із workflow JSON -- Редагування зображень з 1 завантаженим reference image -- Генерація відео з workflow JSON -- Генерація відео з 1 завантаженим reference image +- Генерація зображень із JSON робочого процесу +- Редагування зображень з 1 завантаженим референсним зображенням +- Генерація відео з JSON робочого процесу +- Генерація відео з 1 завантаженим референсним зображенням - Генерація музики або аудіо через спільний інструмент `music_generate` -- Завантаження результату з налаштованого Node або з усіх відповідних output Node +- Завантаження результатів із налаштованого вузла або з усіх відповідних вузлів виводу -## Швидкий старт +## Початок роботи -Виберіть між запуском ComfyUI на власній машині або використанням Comfy Cloud. +Оберіть між запуском ComfyUI на власному комп’ютері або використанням Comfy Cloud. - **Найкраще для:** запуску власного екземпляра ComfyUI на вашій машині або в LAN. + **Найкраще підходить для:** запуску власного екземпляра ComfyUI на вашому комп’ютері або в LAN. - Переконайтеся, що ваш локальний екземпляр ComfyUI працює (типово `http://127.0.0.1:8188`). + Переконайтеся, що ваш локальний екземпляр ComfyUI запущено (типово `http://127.0.0.1:8188`). - - Експортуйте або створіть файл workflow JSON для ComfyUI. Зверніть увагу на ID Node для Node введення prompt і output Node, з якого OpenClaw має читати результат. + + Експортуйте або створіть JSON-файл робочого процесу ComfyUI. Запишіть ідентифікатори вузлів для вузла введення prompt і вузла виводу, з якого OpenClaw має читати дані. - - Задайте `mode: "local"` і вкажіть файл workflow. Ось мінімальний приклад для зображень: + + Встановіть `mode: "local"` і вкажіть файл вашого робочого процесу. Ось мінімальний приклад для зображень: ```json5 { - models: { - providers: { + plugins: { + entries: { comfy: { - mode: "local", - baseUrl: "http://127.0.0.1:8188", - image: { - workflowPath: "./workflows/flux-api.json", - promptNodeId: "6", - outputNodeId: "9", + config: { + mode: "local", + baseUrl: "http://127.0.0.1:8188", + image: { + workflowPath: "./workflows/flux-api.json", + promptNodeId: "6", + outputNodeId: "9", + }, }, }, }, @@ -69,8 +71,8 @@ OpenClaw постачається з вбудованим Plugin `comfy` для } ``` - - Вкажіть OpenClaw на модель `comfy/workflow` для можливості, яку ви налаштували: + + Вкажіть для OpenClaw модель `comfy/workflow` для налаштованої можливості: ```json5 { @@ -94,14 +96,14 @@ OpenClaw постачається з вбудованим Plugin `comfy` для - **Найкраще для:** запуску workflow у Comfy Cloud без керування локальними GPU-ресурсами. + **Найкраще підходить для:** запуску робочих процесів у Comfy Cloud без керування локальними GPU-ресурсами. - - Зареєструйтеся на [comfy.org](https://comfy.org) і створіть API key у панелі керування обліковим записом. + + Зареєструйтеся на [comfy.org](https://comfy.org) і згенеруйте API-ключ на інформаційній панелі свого облікового запису. - - Передайте ключ одним із цих способів: + + Надайте свій ключ одним із цих способів: ```bash # Змінна середовища (рекомендовано) @@ -111,25 +113,27 @@ OpenClaw постачається з вбудованим Plugin `comfy` для export COMFY_CLOUD_API_KEY="your-key" # Або безпосередньо в конфігурації - openclaw config set models.providers.comfy.apiKey "your-key" + openclaw config set plugins.entries.comfy.config.apiKey "your-key" ``` - - Експортуйте або створіть файл workflow JSON для ComfyUI. Зверніть увагу на ID Node для Node введення prompt і output Node. + + Експортуйте або створіть JSON-файл робочого процесу ComfyUI. Запишіть ідентифікатори вузлів для вузла введення prompt і вузла виводу. - - Задайте `mode: "cloud"` і вкажіть файл workflow: + + Встановіть `mode: "cloud"` і вкажіть файл вашого робочого процесу: ```json5 { - models: { - providers: { + plugins: { + entries: { comfy: { - mode: "cloud", - image: { - workflowPath: "./workflows/flux-api.json", - promptNodeId: "6", - outputNodeId: "9", + config: { + mode: "cloud", + image: { + workflowPath: "./workflows/flux-api.json", + promptNodeId: "6", + outputNodeId: "9", + }, }, }, }, @@ -138,10 +142,10 @@ OpenClaw постачається з вбудованим Plugin `comfy` для ``` - У режимі cloud `baseUrl` типово дорівнює `https://cloud.comfy.org`. Задавати `baseUrl` потрібно лише якщо ви використовуєте власний cloud endpoint. + У режимі cloud значення `baseUrl` типово дорівнює `https://cloud.comfy.org`. Вам потрібно встановлювати `baseUrl` лише якщо ви використовуєте власну cloud endpoint. - + ```json5 { agents: { @@ -166,29 +170,31 @@ OpenClaw постачається з вбудованим Plugin `comfy` для ## Конфігурація -Comfy підтримує спільні налаштування з’єднання верхнього рівня плюс секції workflow для окремих можливостей (`image`, `video`, `music`): +Comfy підтримує спільні налаштування з’єднання верхнього рівня, а також розділи робочих процесів для кожної можливості (`image`, `video`, `music`): ```json5 { - models: { - providers: { + plugins: { + entries: { comfy: { - mode: "local", - baseUrl: "http://127.0.0.1:8188", - image: { - workflowPath: "./workflows/flux-api.json", - promptNodeId: "6", - outputNodeId: "9", - }, - video: { - workflowPath: "./workflows/video-api.json", - promptNodeId: "12", - outputNodeId: "21", - }, - music: { - workflowPath: "./workflows/music-api.json", - promptNodeId: "3", - outputNodeId: "18", + config: { + mode: "local", + baseUrl: "http://127.0.0.1:8188", + image: { + workflowPath: "./workflows/flux-api.json", + promptNodeId: "6", + outputNodeId: "9", + }, + video: { + workflowPath: "./workflows/video-api.json", + promptNodeId: "12", + outputNodeId: "21", + }, + music: { + workflowPath: "./workflows/music-api.json", + promptNodeId: "3", + outputNodeId: "18", + }, }, }, }, @@ -198,38 +204,38 @@ Comfy підтримує спільні налаштування з’єднан ### Спільні ключі -| Key | Type | Description | -| --------------------- | ---------------------- | ------------------------------------------------------------------------------------- | -| `mode` | `"local"` або `"cloud"` | Режим з’єднання. | -| `baseUrl` | string | Типово `http://127.0.0.1:8188` для local або `https://cloud.comfy.org` для cloud. | -| `apiKey` | string | Необов’язковий вбудований ключ, альтернатива env vars `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY`. | -| `allowPrivateNetwork` | boolean | Дозволити приватний/LAN `baseUrl` у режимі cloud. | +| Key | Type | Description | +| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------- | +| `mode` | `"local"` or `"cloud"` | Режим з’єднання. | +| `baseUrl` | string | Типово `http://127.0.0.1:8188` для локального режиму або `https://cloud.comfy.org` для cloud. | +| `apiKey` | string | Необов’язковий вбудований ключ, альтернатива змінним середовища `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY`. | +| `allowPrivateNetwork` | boolean | Дозволити приватний/LAN `baseUrl` у режимі cloud. | -### Ключі для окремих можливостей +### Ключі для кожної можливості -Ці ключі застосовуються всередині секцій `image`, `video` або `music`: +Ці ключі застосовуються всередині розділів `image`, `video` або `music`: | Key | Required | Default | Description | | ---------------------------- | -------- | -------- | ---------------------------------------------------------------------------- | -| `workflow` або `workflowPath` | Так | -- | Шлях до файлу workflow JSON ComfyUI. | -| `promptNodeId` | Так | -- | ID Node, який отримує текстовий prompt. | -| `promptInputName` | Ні | `"text"` | Ім’я входу в Node prompt. | -| `outputNodeId` | Ні | -- | ID Node, з якого читається результат. Якщо не задано, використовуються всі відповідні output Node. | -| `pollIntervalMs` | Ні | -- | Інтервал опитування в мілісекундах для завершення завдання. | -| `timeoutMs` | Ні | -- | Тайм-аут запуску workflow в мілісекундах. | +| `workflow` or `workflowPath` | Yes | -- | Шлях до JSON-файлу робочого процесу ComfyUI. | +| `promptNodeId` | Yes | -- | Ідентифікатор вузла, який отримує текстовий prompt. | +| `promptInputName` | No | `"text"` | Назва входу на вузлі prompt. | +| `outputNodeId` | No | -- | Ідентифікатор вузла, з якого читати результат. Якщо не вказано, використовуються всі відповідні вузли виводу. | +| `pollIntervalMs` | No | -- | Інтервал опитування в мілісекундах для завершення завдання. | +| `timeoutMs` | No | -- | Тайм-аут у мілісекундах для запуску робочого процесу. | -Секції `image` і `video` також підтримують: +Розділи `image` і `video` також підтримують: -| Key | Required | Default | Description | -| --------------------- | ------------------------------------ | --------- | --------------------------------------------------- | -| `inputImageNodeId` | Так (коли передається reference image) | -- | ID Node, який отримує завантажене reference image. | -| `inputImageInputName` | Ні | `"image"` | Ім’я входу в Node зображення. | +| Key | Required | Default | Description | +| --------------------- | ------------------------------------ | --------- | ----------------------------------------------------- | +| `inputImageNodeId` | Yes (when passing a reference image) | -- | Ідентифікатор вузла, який отримує завантажене референсне зображення. | +| `inputImageInputName` | No | `"image"` | Назва входу на вузлі зображення. | -## Деталі workflow +## Деталі робочого процесу - - Задайте типову модель зображень як `comfy/workflow`: + + Встановіть типову модель зображень на `comfy/workflow`: ```json5 { @@ -243,21 +249,23 @@ Comfy підтримує спільні налаштування з’єднан } ``` - **Приклад редагування з reference image:** + **Приклад редагування з референсним зображенням:** - Щоб увімкнути редагування зображень із завантаженим reference image, додайте `inputImageNodeId` до конфігурації image: + Щоб увімкнути редагування зображень із завантаженим референсним зображенням, додайте `inputImageNodeId` до конфігурації `image`: ```json5 { - models: { - providers: { + plugins: { + entries: { comfy: { - image: { - workflowPath: "./workflows/edit-api.json", - promptNodeId: "6", - inputImageNodeId: "7", - inputImageInputName: "image", - outputNodeId: "9", + config: { + image: { + workflowPath: "./workflows/edit-api.json", + promptNodeId: "6", + inputImageNodeId: "7", + inputImageInputName: "image", + outputNodeId: "9", + }, }, }, }, @@ -267,8 +275,8 @@ Comfy підтримує спільні налаштування з’єднан - - Задайте типову модель відео як `comfy/workflow`: + + Встановіть типову модель відео на `comfy/workflow`: ```json5 { @@ -282,58 +290,60 @@ Comfy підтримує спільні налаштування з’єднан } ``` - Workflow відео Comfy підтримують text-to-video та image-to-video через налаштований граф. + Відеоробочі процеси Comfy підтримують text-to-video та image-to-video через налаштований граф. - OpenClaw не передає вхідні відео у workflow Comfy. Як вхідні дані підтримуються лише текстові prompt і одне reference image. + OpenClaw не передає вхідні відео в робочі процеси Comfy. Як вхідні дані підтримуються лише текстові prompt і окремі референсні зображення. - - Вбудований Plugin реєструє провайдера генерації музики для виходів аудіо або музики, визначених workflow, які доступні через спільний інструмент `music_generate`: + + Вбудований Plugin реєструє провайдер генерації музики для визначених робочим процесом аудіо- або музичних виходів, доступний через спільний інструмент `music_generate`: ```text /tool music_generate prompt="Warm ambient synth loop with soft tape texture" ``` - Використовуйте секцію конфігурації `music`, щоб вказати ваш workflow JSON для аудіо й output Node. + Використовуйте розділ конфігурації `music`, щоб вказати JSON вашого аудіоробочого процесу та вузол виводу. - - Наявна верхньорівнева конфігурація image (без вкладеної секції `image`) усе ще працює: + + Наявна конфігурація зображень верхнього рівня (без вкладеного розділу `image`) усе ще працює: ```json5 { - models: { - providers: { + plugins: { + entries: { comfy: { - workflowPath: "./workflows/flux-api.json", - promptNodeId: "6", - outputNodeId: "9", + config: { + workflowPath: "./workflows/flux-api.json", + promptNodeId: "6", + outputNodeId: "9", + }, }, }, }, } ``` - OpenClaw трактує цю застарілу форму як конфігурацію workflow для image. Негайна міграція не потрібна, але для нових налаштувань рекомендуються вкладені секції `image` / `video` / `music`. + OpenClaw розглядає цю застарілу форму як конфігурацію робочого процесу для зображень. Вам не потрібно негайно виконувати міграцію, але для нових налаштувань рекомендовано вкладені розділи `image` / `video` / `music`. - Якщо ви використовуєте лише генерацію зображень, застаріла пласка конфігурація і нова вкладена секція `image` функціонально еквівалентні. + Якщо ви використовуєте лише генерацію зображень, застаріла плоска конфігурація та новий вкладений розділ `image` функціонально еквівалентні. - - Для вбудованого Plugin є opt-in покриття live-тестами: + + Для вбудованого Plugin доступне live-покриття за opt-in: ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` - Live-тест пропускає окремі сценарії для image, video або music, якщо відповідна секція workflow Comfy не налаштована. + Live test пропускає окремі сценарії для зображень, відео або музики, якщо не налаштовано відповідний розділ робочого процесу Comfy. @@ -342,18 +352,18 @@ Comfy підтримує спільні налаштування з’єднан - Налаштування та використання інструмента генерації зображень. + Конфігурація та використання інструмента генерації зображень. - Налаштування та використання інструмента генерації відео. + Конфігурація та використання інструмента генерації відео. - Налаштування інструмента генерації музики й аудіо. + Налаштування інструмента генерації музики та аудіо. - Огляд усіх провайдерів і model ref. + Огляд усіх провайдерів і посилань на моделі. - - Повний довідник конфігурації, включно з типовими значеннями агентів. + + Повний довідник із конфігурації, включно з типовими значеннями агентів. diff --git a/docs/uk/tools/music-generation.md b/docs/uk/tools/music-generation.md index 11294d94a..b3167f368 100644 --- a/docs/uk/tools/music-generation.md +++ b/docs/uk/tools/music-generation.md @@ -1,15 +1,15 @@ --- read_when: - - Генерування музики або аудіо через агента - - Налаштування провайдерів і моделей генерації музики + - Генерація музики або аудіо через агента + - Налаштування провайдерів і моделей для генерації музики - Розуміння параметрів інструмента `music_generate` -summary: Генеруйте музику за допомогою спільних провайдерів, включно з Plugin на основі workflow +summary: Створюйте музику зі спільними провайдерами, включно з Plugin, що працюють на основі workflow title: Генерація музики x-i18n: - generated_at: "2026-04-24T03:49:25Z" + generated_at: "2026-04-24T20:32:18Z" model: gpt-5.4 provider: openai - source_hash: c5fe640c6b83f6f2cf5ad8e57294da147f241706c30eee0d0eb6f7d82cbbe0d3 + source_hash: cc6da03cd1cc5728e903b3c5bf0c47da65642842e38c1006419e2f2ce2400bda source_path: tools/music-generation.md workflow: 15 --- @@ -18,22 +18,21 @@ x-i18n: спільну можливість генерації музики з налаштованими провайдерами, такими як Google, MiniMax і ComfyUI, налаштований через workflow. -Для сесій агента на основі спільних провайдерів OpenClaw запускає генерацію музики як -фонове завдання, відстежує її в ledger завдань, а потім знову пробуджує агента, коли -трек готовий, щоб агент міг опублікувати завершене аудіо назад в -оригінальний канал. +Для сеансів агента на основі спільних провайдерів OpenClaw запускає генерацію музики як +фонове завдання, відстежує її в журналі завдань, а потім знову активує агента, коли +трек готовий, щоб агент міг опублікувати готове аудіо назад у вихідний канал. -Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API key провайдера. +Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` в інструментах вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або встановіть API-ключ провайдера. ## Швидкий старт -### Генерація через спільний провайдер +### Генерація на основі спільного провайдера -1. Задайте API key принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або +1. Установіть API-ключ принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або `MINIMAX_API_KEY`. -2. За потреби задайте бажану модель: +2. За бажанням установіть бажану модель: ```json5 { @@ -47,68 +46,68 @@ MiniMax і ComfyUI, налаштований через workflow. } ``` -3. Попросіть агента: _"Згенеруй жвавий synthpop-трек про нічну поїздку +3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку крізь неонове місто."_ -Агент викличе `music_generate` автоматично. Додавання до allowlist інструментів не потрібне. +Агент викликає `music_generate` автоматично. Дозволений список інструментів не потрібен. -Для прямих синхронних контекстів без запуску агента, прив’язаного до сесії, вбудований -інструмент усе одно повертається до inline-генерації та повертає фінальний шлях до медіа в -результаті інструмента. +Для прямих синхронних контекстів без запуску агента на основі сеансу вбудований +інструмент усе одно переходить до вбудованої генерації та повертає фінальний шлях до медіа в результаті інструмента. -Приклади prompt: +Приклади запитів: ```text Згенеруй кінематографічний фортепіанний трек із м’якими струнними та без вокалу. ``` ```text -Згенеруй енергійний chiptune-луп про запуск ракети на світанку. +Згенеруй енергійну chiptune-петлю про запуск ракети на світанку. ``` ### Генерація Comfy на основі workflow -Вбудований Plugin `comfy` підключається до спільного інструмента `music_generate` через -registry провайдерів генерації музики. +Убудований Plugin `comfy` підключається до спільного інструмента `music_generate` через +реєстр провайдерів генерації музики. -1. Налаштуйте `models.providers.comfy.music` з workflow JSON і - вузлами prompt/output. -2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. -3. Попросіть агента створити музику або викличте інструмент напряму. +1. Налаштуйте `plugins.entries.comfy.config.music` за допомогою JSON workflow та + вузлів prompt/output. +2. Якщо ви використовуєте Comfy Cloud, установіть `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. +3. Попросіть агента створити музику або викличте інструмент безпосередньо. Приклад: ```text -/tool music_generate prompt="Теплий ambient synth-луп із м’якою касетною текстурою" +/tool music_generate prompt="Тепла ембієнтна synth-петля з м’якою текстурою стрічки" ``` -## Підтримка спільних вбудованих провайдерів +## Підтримка вбудованих спільних провайдерів -| Провайдер | Типова модель | Вхідні reference-дані | Підтримувані параметри | API key | -| --------- | --------------------- | --------------------- | ------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | До 1 зображення | Музика або аудіо, визначені workflow | `COMFY_API_KEY`, `COMFY_CLOUD_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-ключ | +| --------- | ----------------------- | ---------------- | ----------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | До 1 зображення | Визначені workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_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` | ### Матриця оголошених можливостей -Це явний контракт режимів, який використовують `music_generate`, contract tests -і спільна live-перевірка. +Це явний контракт режимів, який використовують `music_generate`, контрактні тести +та спільний live sweep. | Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live lanes | | --------- | ---------- | ------ | ----------------- | ------------------------------------------------------------------------- | -| ComfyUI | Так | Так | 1 зображення | Не входить до спільної перевірки; покривається `extensions/comfy/comfy.live.test.ts` | +| ComfyUI | Так | Так | 1 зображення | Не входить до спільного sweep; покривається `extensions/comfy/comfy.live.test.ts` | | Google | Так | Так | 10 зображень | `generate`, `edit` | | MiniMax | Так | Ні | Немає | `generate` | -Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі -під час runtime: +Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі під +час виконання: ```text /tool music_generate action=list ``` -Використовуйте `action: "status"`, щоб перевірити активне завдання музики, прив’язане до сесії: +Використовуйте `action: "status"`, щоб перевірити активне завдання генерації музики +на основі поточного сеансу: ```text /tool music_generate action=status @@ -117,53 +116,56 @@ registry провайдерів генерації музики. Приклад прямої генерації: ```text -/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та легким дощем" instrumental=true +/tool music_generate prompt="Мрійливий lo-fi hip hop із текстурою вінілу та ніжним дощем" instrumental=true ``` ## Параметри вбудованого інструмента -| Параметр | Тип | Опис | -| ---------------- | -------- | ---------------------------------------------------------------------------------------------- | -| `prompt` | string | Prompt генерації музики (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (за замовчуванням), `"status"` для поточного завдання сесії або `"list"` для перегляду провайдерів | -| `model` | string | Перевизначення provider/model, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | -| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явний вхід lyrics | -| `instrumental` | boolean | Запит лише інструментального результату, якщо провайдер це підтримує | -| `image` | string | Шлях або URL до одного reference-зображення | -| `images` | string[] | Кілька reference-зображень (до 10) | -| `durationSeconds`| number | Цільова тривалість у секундах, якщо провайдер підтримує підказки тривалості | -| `timeoutMs` | 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 | Необов’язковий текст пісні, якщо провайдер підтримує явний вхід lyrics | +| `instrumental` | boolean | Запит на інструментальний результат без вокалу, якщо провайдер це підтримує | +| `image` | string | Шлях або URL одного опорного зображення | +| `images` | string[] | Кілька опорних зображень (до 10) | +| `durationSeconds` | number | Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості | +| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах | +| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо провайдер це підтримує | +| `filename` | string | Підказка щодо назви вихідного файлу | Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження, -такі як кількість входів, перед надсиланням. Коли провайдер підтримує тривалість, але -використовує коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує її -до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки ігноруються -з попередженням, коли вибраний провайдер або модель не може їх підтримати. +такі як кількість вхідних даних, перед надсиланням. Якщо провайдер підтримує тривалість, але +використовує менший максимум, ніж запитане значення, OpenClaw автоматично обмежує його +до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки +ігноруються з попередженням, якщо вибраний провайдер або модель не можуть їх застосувати. -Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує тривалість під час provider fallback, повернене `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує відповідність від запитаного до застосованого. +Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує +тривалість під час резервного переходу між провайдерами, повернене `durationSeconds` відображає +надіслане значення, а `details.normalization.durationSeconds` показує зіставлення між +запитаним і застосованим значеннями. -## Асинхронна поведінка для шляху зі спільним провайдером +## Асинхронна поведінка для шляху на основі спільного провайдера -- Запуски агента, прив’язані до сесії: `music_generate` створює фонове завдання, одразу повертає відповідь про старт/завдання та публікує готовий трек пізніше в наступному повідомленні агента. -- Запобігання дублюванню: поки це фонове завдання все ще має стан `queued` або `running`, подальші виклики `music_generate` у тій самій сесії повертають статус завдання замість запуску нової генерації. -- Перевірка статусу: використовуйте `action: "status"`, щоб перевірити активне музичне завдання, прив’язане до сесії, не запускаючи нову генерацію. -- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити queued, running і terminal status для генерації. -- Пробудження після завершення: OpenClaw інжектує внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати user-facing наступне повідомлення. -- Підказка для prompt: наступні ходи користувача/вручну в тій самій сесії отримують невелику runtime-підказку, коли музичне завдання вже виконується, щоб модель не викликала `music_generate` знову бездумно. -- Резервний режим без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються inline і повертають фінальний результат аудіо в тому самому ході. +- Запуски агента на основі сеансу: `music_generate` створює фонове завдання, негайно повертає відповідь started/task, а готовий трек публікує пізніше в наступному повідомленні агента. +- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тому самому сеансі повертають стан завдання замість запуску нової генерації. +- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерації музики для поточного сеансу без запуску нового. +- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати стани queued, running і terminal для генерації. +- Активація після завершення: OpenClaw вставляє внутрішню подію завершення назад у той самий сеанс, щоб модель могла сама написати наступне повідомлення для користувача. +- Підказка в prompt: наступні користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку під час виконання, коли завдання генерації музики вже виконується, щоб модель не викликала `music_generate` знову навмання. +- Резервний варіант без сеансу: прямі/локальні контексти без справжнього сеансу агента все одно виконуються вбудовано та повертають фінальний результат аудіо в тому самому ході. ### Життєвий цикл завдання -Кожен запит `music_generate` проходить чотири стани: +Кожен запит `music_generate` проходить через чотири стани: 1. **queued** -- завдання створено, очікує, поки провайдер прийме його. -2. **running** -- провайдер обробляє його (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості). -3. **succeeded** -- трек готовий; агент прокидається й публікує його в розмову. -4. **failed** -- помилка провайдера або тайм-аут; агент прокидається з деталями помилки. +2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера та тривалості). +3. **succeeded** -- трек готовий; агент активується й публікує його в розмову. +4. **failed** -- помилка провайдера або тайм-аут; агент активується з відомостями про помилку. -Перевірка статусу через CLI: +Перевірка стану з CLI: ```bash openclaw tasks list @@ -171,7 +173,7 @@ openclaw tasks show openclaw tasks cancel ``` -Запобігання дублюванню: якщо для поточної сесії музичне завдання вже має стан `queued` або `running`, `music_generate` повертає статус наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. +Запобігання дублюванню: якщо для поточного сеансу завдання генерації музики вже має стан `queued` або `running`, `music_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. ## Конфігурація @@ -192,29 +194,29 @@ openclaw tasks cancel ### Порядок вибору провайдера -Під час генерації музики OpenClaw пробує провайдерів у такому порядку: +Під час генерації музики OpenClaw намагається використовувати провайдерів у такому порядку: -1. параметр `model` із виклику інструмента, якщо агент його задає -2. `musicGenerationModel.primary` з config -3. `musicGenerationModel.fallbacks` по черзі -4. Автовизначення лише через значення провайдерів за замовчуванням із підтримкою auth: - - спочатку поточний провайдер за замовчуванням - - далі решта зареєстрованих провайдерів генерації музики в порядку provider-id +1. параметр `model` із виклику інструмента, якщо агент його вказує +2. `musicGenerationModel.primary` із конфігурації +3. `musicGenerationModel.fallbacks` у заданому порядку +4. Автовизначення лише з використанням типових значень провайдера на основі автентифікації: + - спочатку поточний типовий провайдер + - решта зареєстрованих провайдерів генерації музики в порядку provider-id -Якщо один провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо -помиляються всі, помилка містить деталі кожної спроби. +Якщо провайдер зазнає невдачі, автоматично випробовується наступний кандидат. Якщо не спрацьовують усі, помилка +містить відомості про кожну спробу. -Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб +Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація музики використовувала лише явні записи `model`, `primary` і `fallbacks`. ## Примітки щодо провайдерів - Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує - prompt, необов’язковий текст lyrics і необов’язкові reference-зображення. + prompt, необов’язковий текст lyrics і необов’язкові опорні зображення. - MiniMax використовує пакетний endpoint `music_generation`. Поточний вбудований потік підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та - вивід mp3. -- Підтримка ComfyUI базується на workflow і залежить від налаштованого графа та + вивід у mp3. +- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та зіставлення вузлів для полів prompt/output. ## Режими можливостей провайдера @@ -222,9 +224,9 @@ openclaw tasks cancel Спільний контракт генерації музики тепер підтримує явні оголошення режимів: - `generate` для генерації лише за prompt -- `edit`, коли запит включає одне або кілька reference-зображень +- `edit`, коли запит містить одне або більше опорних зображень -Нові реалізації провайдерів мають віддавати перевагу явним блокам режимів: +Нові реалізації провайдерів мають надавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -242,20 +244,20 @@ capabilities: { } ``` -Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і -`supportsFormat`, недостатньо для оголошення підтримки edit. Провайдери мають -явно оголошувати `generate` і `edit`, щоб live tests, contract tests і +Застарілі плоскі поля, такі як `maxInputImages`, `supportsLyrics` і +`supportsFormat`, недостатні для оголошення підтримки редагування. Провайдери мають +явно оголошувати `generate` і `edit`, щоб live-тести, контрактні тести та спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів. -## Вибір правильного шляху +## Як вибрати правильний шлях -- Використовуйте шлях зі спільним провайдером, коли вам потрібні вибір моделі, provider failover і вбудований асинхронний потік task/status. -- Використовуйте шлях Plugin, як-от ComfyUI, коли вам потрібен власний граф workflow або провайдер, який не входить до спільної вбудованої можливості генерації музики. +- Використовуйте шлях на основі спільного провайдера, якщо вам потрібні вибір моделі, резервне перемикання між провайдерами та вбудований асинхронний потік завдань/стану. +- Використовуйте шлях через Plugin, наприклад ComfyUI, якщо вам потрібен власний граф workflow або провайдер, який не входить до спільної вбудованої можливості генерації музики. - Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть з [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). -## Live tests +## Live-тести -Live-покриття за явним увімкненням для спільних вбудованих провайдерів: +Live-покриття за вибором для спільних вбудованих провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts @@ -267,29 +269,31 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv pnpm test:live:media music ``` -Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, за замовчуванням віддає перевагу live/env API keys над збереженими auth profiles і запускає покриття як `generate`, так і оголошеного `edit`, коли провайдер вмикає режим edit. +Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово +надає перевагу API-ключам live/env перед збереженими профілями автентифікації та запускає покриття +і `generate`, і оголошеного `edit`, коли провайдер вмикає режим редагування. Наразі це означає: - `google`: `generate` плюс `edit` - `minimax`: лише `generate` -- `comfy`: окреме live-покриття Comfy, а не спільна перевірка провайдерів +- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів -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 workflow для зображень і відео, коли ці +Файл live для Comfy також покриває workflow зображень і відео comfy, коли ці розділи налаштовані. ## Пов’язане - [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate` -- [Довідник з конфігурації](/uk/gateway/config-agents#agent-defaults) - config `musicGenerationModel` +- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) - конфігурація `musicGenerationModel` - [ComfyUI](/uk/providers/comfy) - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax) -- [Models](/uk/concepts/models) - конфігурація моделей і failover +- [Моделі](/uk/concepts/models) - конфігурація моделей і резервне перемикання - [Огляд інструментів](/uk/tools)