From db3e009e5e5cf4cbd1409f306c637254f0c0cd38 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 22:07:27 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/architecture-internals.md | 845 ++++++++++--------- docs/uk/plugins/compatibility.md | 119 ++- docs/uk/plugins/manifest.md | 936 ++++++++++------------ docs/uk/providers/openai.md | 458 +++++------ docs/uk/tools/tts.md | 590 +++++++------- 5 files changed, 1434 insertions(+), 1514 deletions(-) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 74799495f..cfc189c99 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,154 +1,152 @@ --- read_when: - - Реалізація хуків часу виконання провайдера, життєвого циклу каналу або наборів пакетів + - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - Налагодження порядку завантаження Plugin або стану реєстру - - Додавання нової можливості Plugin або Plugin рушія контексту -summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки часу виконання, HTTP-маршрути та довідкові таблиці' + - Додавання нової Plugin-можливості або Plugin рушія контексту +summary: 'Внутрішня будова архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, маршрути HTTP і довідкові таблиці' title: Внутрішні механізми архітектури Plugin x-i18n: - generated_at: "2026-05-01T20:39:31Z" + generated_at: "2026-05-01T22:03:42Z" model: gpt-5.5 provider: openai - source_hash: 782ee5f33fe157071cb2936cfb9d1e807b7452c4c6c18364a376d0bd99727b8a + source_hash: d97a5854e830adc6af5848392f8d1da3490b9625cbf0af0cc46f49a8719e8e41 source_path: plugins/architecture-internals.md workflow: 16 --- -Для публічної моделі можливостей, форм Plugin та контрактів володіння/виконання -див. [Архітектуру Plugin](/uk/plugins/architecture). Ця сторінка є -довідником з внутрішньої механіки: конвеєра завантаження, реєстру, runtime-хуків, +Для публічної моделі можливостей, форм Plugin і контрактів +володіння/виконання див. [архітектуру Plugin](/uk/plugins/architecture). Ця сторінка є +довідником щодо внутрішніх механік: конвеєра завантаження, реєстру, runtime-хуків, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. знаходить корені кандидатів Plugin -2. читає нативні або сумісні маніфести пакетів і метадані пакетів +1. виявляє корені кандидатів Plugin +2. читає нативні або сумісні маніфести бандлів і метадані пакетів 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. визначає ввімкнення для кожного кандидата 6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; - незбиранi нативні plugins використовують jiti + незібрані нативні Plugin використовують jiti 7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin -8. відкриває реєстр для команд/runtime-поверхонь +8. відкриває реєстр для команд і runtime-поверхонь -`activate` — це застарілий псевдонім для `register` — завантажувач визначає наявний варіант (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugins віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register`: завантажувач визначає, що наявне (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin віддавайте перевагу `register`. -Запобіжні перевірки виконуються **до** runtime-виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, -або володіння шляхом виглядає підозрілим для невбудованих plugins. +Захисні перевірки відбуваються **до** runtime-виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня Plugin, шлях доступний на запис усім +користувачам або право власності на шлях виглядає підозрілим для невбудованих Plugin. ### Поведінка з пріоритетом маніфесту Маніфест є джерелом істини для площини керування. OpenClaw використовує його, щоб: - ідентифікувати Plugin -- знаходити оголошені канали/skills/схему конфігурації або можливості пакета +- виявляти оголошені канали/Skills/схему конфігурації або можливості бандла - перевіряти `plugins.entries..config` - доповнювати мітки/заповнювачі Control UI - показувати метадані встановлення/каталогу - зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin -Для нативних plugins runtime-модуль є частиною площини даних. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдерів. +Для нативних Plugin runtime-модуль є частиною площини даних. Він реєструє +фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдера. Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування. -Це дескриптори лише метаданих для планування активації та виявлення налаштування; +Це дескриптори лише з метаданими для планування активації та виявлення налаштування; вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`. Перші live-споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, -щоб звузити завантаження Plugin перед ширшою матеріалізацією реєстру: +щоб звужувати завантаження Plugin перед ширшою матеріалізацією реєстру: -- завантаження CLI звужується до plugins, які володіють запитаною основною командою -- розв’язання налаштування каналу/Plugin звужується до plugins, які володіють запитаним - id каналу -- явне розв’язання налаштування/runtime провайдера звужується до plugins, які володіють запитаним - id провайдера +- завантаження CLI звужується до Plugin, які володіють запитаною основною командою +- налаштування каналу/визначення Plugin звужується до Plugin, які володіють запитаним + ідентифікатором каналу +- явне налаштування провайдера/визначення runtime звужується до Plugin, які володіють запитаним + ідентифікатором провайдера - планування запуску Gateway використовує `activation.onStartup` для явних імпортів - під час запуску та відмов від запуску; кожен Plugin має оголошувати це, оскільки OpenClaw - відходить від неявних імпортів під час запуску, тоді як plugins без статичних - метаданих можливостей і без `activation.onStartup` усе ще використовують - застарілий неявний sidecar fallback під час запуску для сумісності + під час запуску та явних відмов від запуску; Plugin без метаданих запуску завантажуються лише + через вужчі тригери активації -Планувальник активації відкриває як API лише з ids для наявних викликачів, так і +Планувальник активації відкриває як API лише з ідентифікаторами для наявних викликачів, так і API плану для нової діагностики. Записи плану повідомляють, чому було вибрано Plugin, -відокремлюючи явні підказки планувальника `activation.*` від fallback володіння -з маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, +відокремлюючи явні планувальні підказки `activation.*` від fallback-володіння з маніфесту, +такого як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і хуки. Цей поділ причин є межею сумісності: наявні метадані Plugin продовжують працювати, а новий код може виявляти широкі підказки або fallback-поведінку без зміни семантики runtime-завантаження. -Виявлення налаштування тепер віддає перевагу ids, якими володіють дескриптори, як-от `setup.providers` і -`setup.cliBackends`, щоб звузити plugins-кандидати, перш ніж повертатися до -`setup-api` для plugins, яким досі потрібні runtime-хуки під час налаштування. Списки +Виявлення налаштування тепер надає перевагу ідентифікаторам, якими володіє дескриптор, як-от `setup.providers` і +`setup.cliBackends`, щоб звузити кандидатів Plugin перед fallback до +`setup-api` для Plugin, яким досі потрібні runtime-хуки під час налаштування. Списки налаштування провайдерів використовують маніфест `providerAuthChoices`, варіанти налаштування, -виведені з дескрипторів, і метадані каталогу встановлення без завантаження runtime провайдера. Явне -`setup.requiresRuntime: false` є descriptor-only відсіканням; пропущене -`requiresRuntime` зберігає застарілий fallback setup-api для сумісності. Якщо більш ніж -один виявлений Plugin претендує на той самий нормалізований id провайдера налаштування або CLI -backend, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на +похідні від дескриптора, і метадані каталогу встановлення без завантаження runtime провайдера. Явне +`setup.requiresRuntime: false` є descriptor-only відсіченням; пропущений +`requiresRuntime` зберігає застарілий fallback setup-api для сумісності. Якщо більше +ніж один виявлений Plugin заявляє той самий нормалізований ідентифікатор провайдера налаштування або CLI +бекенда, пошук налаштування відхиляє неоднозначного власника, а не покладається на порядок виявлення. Коли runtime налаштування все ж виконується, діагностика реєстру повідомляє про розбіжність між `setup.providers` / `setup.cliBackends` і провайдерами або CLI -backends, зареєстрованими setup-api, не блокуючи застарілі plugins. +бекендами, зареєстрованими setup-api, не блокуючи застарілі Plugin. ### Межа кешу Plugin -OpenClaw не кешує результати виявлення Plugin або дані прямого реєстру маніфестів -за часовими вікнами wall-clock. Встановлення, зміни маніфесту та зміни шляхів завантаження -мають ставати видимими під час наступного явного читання метаданих або перебудови знімка. -Парсер файлів маніфесту може тримати обмежений кеш файлових сигнатур, ключований за +OpenClaw не кешує результати виявлення Plugin або прямі дані реєстру маніфестів +за вікнами настінного часу. Встановлення, редагування маніфестів і зміни шляхів завантаження +мають стати видимими під час наступного явного читання метаданих або перебудови знімка. +Парсер файлу маніфесту може зберігати обмежений кеш файлових сигнатур, ключований за відкритим шляхом маніфесту, inode, розміром і часовими мітками; цей кеш лише уникає -повторного парсингу незмінених байтів і не повинен кешувати відповіді про виявлення, -реєстр, власника або політику. +повторного парсингу незмінених байтів і не має кешувати відповіді щодо виявлення, +реєстру, власника або політики. -Безпечний швидкий шлях метаданих — явне володіння об’єктами, а не прихований кеш. +Безпечний швидкий шлях метаданих — це явне володіння об’єктами, а не прихований кеш. Гарячі шляхи запуску Gateway мають передавати поточний `PluginMetadataSnapshot`, -похідну `PluginLookUpTable` або явний реєстр маніфестів через ланцюг викликів. -Перевірка конфігурації, автоматичне ввімкнення під час запуску, bootstrap Plugin і вибір -провайдера можуть повторно використовувати ці об’єкти, поки вони представляють поточну конфігурацію та -інвентар Plugin. Пошук налаштування все ще реконструює метадані маніфесту на вимогу, -якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; зберігайте це -як fallback холодного шляху замість додавання прихованих кешів пошуку. Коли вхідні дані -змінюються, перебудуйте й замініть знімок замість того, щоб мутувати його або зберігати +похідний `PluginLookUpTable` або явний реєстр маніфестів ланцюгом викликів. +Перевірка конфігурації, автоматичне ввімкнення під час запуску, початкове завантаження Plugin і вибір +провайдера можуть повторно використовувати ці об’єкти, доки вони представляють поточну конфігурацію та +інвентар Plugin. Пошук налаштування досі реконструює метадані маніфесту на вимогу, +якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; тримайте це +як fallback холодного шляху, а не додавайте приховані кеші пошуку. Коли вхідні дані +змінюються, перебудуйте й замініть знімок, а не мутуйте його чи зберігайте історичні копії. -Подання активного реєстру Plugin і helpers bootstrap для вбудованих каналів -мають перераховуватися з поточного реєстру/кореня. Короткоживучі мапи прийнятні -всередині одного виклику, щоб дедуплікувати роботу або захистити повторний вхід; вони не повинні ставати процесними +Подання над активним реєстром Plugin і допоміжні засоби початкового завантаження вбудованих каналів +мають переобчислюватися з поточного реєстру/кореня. Короткоживучі мапи прийнятні +в межах одного виклику для усунення дублювання роботи або захисту від повторного входу; вони не мають ставати процесними кешами метаданих. -Для завантаження Plugin постійний шар кешу — це runtime-завантаження. Він може повторно використовувати -стан завантажувача, коли код або встановлені артефакти фактично завантажуються, як-от: +Для завантаження Plugin постійним шаром кешу є runtime-завантаження. Він може повторно використовувати +стан завантажувача, коли код або встановлені артефакти справді завантажуються, як-от: - `PluginLoaderCacheState` і сумісні активні runtime-реєстри -- кеші jiti/модулів і кеші завантажувача публічних поверхонь, які використовуються, щоб уникати імпорту - тієї самої runtime-поверхні повторно +- кеші jiti/модулів і кеші завантажувача публічних поверхонь, що використовуються, щоб уникнути повторного імпорту + тієї самої runtime-поверхні - кеші файлової системи для встановлених артефактів Plugin -- короткоживучі per-call мапи для нормалізації шляхів або розв’язання дублікатів +- короткоживучі мапи на один виклик для нормалізації шляхів або розв’язання дублікатів -Ці кеші є деталями реалізації площини даних. Вони не повинні відповідати на -питання площини керування, як-от "який Plugin володіє цим провайдером?", якщо +Ці кеші є деталями реалізації площини даних. Вони не мають відповідати на +питання площини керування, як-от «який Plugin володіє цим провайдером?», якщо викликач навмисно не попросив runtime-завантаження. -Не додавайте постійні або wall-clock кеші для: +Не додавайте постійні або прив’язані до настінного часу кеші для: - результатів виявлення - прямих реєстрів маніфестів -- реєстрів маніфестів, реконструйованих із індексу встановлених Plugin +- реєстрів маніфестів, реконструйованих із встановленого індексу Plugin - пошуку власника провайдера, приглушення моделі, політики провайдера або метаданих публічних артефактів -- будь-якої іншої відповіді, виведеної з маніфесту, де змінений маніфест, встановлений індекс +- будь-якої іншої відповіді, похідної від маніфесту, де змінений маніфест, встановлений індекс або шлях завантаження має бути видимим під час наступного читання метаданих -Викликачі, які перебудовують метадані маніфесту зі збереженого індексу встановлених Plugin, -реконструюють цей реєстр на вимогу. Встановлений індекс — це довговічний -стан площини джерела; він не є прихованим внутрішньопроцесним кешем метаданих. +Викликачі, які перебудовують метадані маніфесту зі збереженого встановленого індексу Plugin, +реконструюють цей реєстр на вимогу. Встановлений індекс є довговічним станом +площини джерела; це не прихований внутрішньопроцесний кеш метаданих. ## Модель реєстру -Завантажені plugins не мутують напряму випадкові core-глобальні змінні. Вони реєструються в +Завантажені Plugin не мутують напряму випадкові глобальні об’єкти ядра. Вони реєструються в центральному реєстрі Plugin. Реєстр відстежує: @@ -158,28 +156,28 @@ OpenClaw не кешує результати виявлення Plugin або - застарілі хуки та типізовані хуки - канали - провайдерів -- обробники Gateway RPC +- RPC-обробники Gateway - HTTP-маршрути - реєстратори CLI - фонові служби -- команди, якими володіє Plugin +- команди, якими володіють Plugin -Потім core-функції читають із цього реєстру замість того, щоб напряму звертатися до модулів Plugin. -Це зберігає завантаження односпрямованим: +Потім функції ядра читають із цього реєстру, а не спілкуються з модулями Plugin +напряму. Це зберігає завантаження односпрямованим: - модуль Plugin -> реєстрація в реєстрі -- core runtime -> споживання реєстру +- runtime ядра -> споживання реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості core-поверхонь потрібна лише -одна точка інтеграції: "читати реєстр", а не "робити спеціальний випадок для кожного -модуля Plugin". +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна лише +одна інтеграційна точка: «читати реєстр», а не «обробляти окремо кожен модуль +Plugin». -## Callback-и прив’язки розмови +## Callback-и прив’язування розмови -Plugins, які прив’язують розмову, можуть реагувати, коли схвалення розв’язано. +Plugin, які прив’язують розмову, можуть реагувати, коли approval розв’язано. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після схвалення -або відхилення запиту на прив’язку: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на прив’язування +схвалено або відхилено: ```ts export default { @@ -203,116 +201,117 @@ export default { - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: розв’язана прив’язка для схвалених запитів -- `request`: початковий підсумок запиту, підказка від’єднання, id відправника та +- `binding`: розв’язане прив’язування для схвалених запитів +- `request`: підсумок оригінального запиту, підказка від’єднання, ідентифікатор відправника та метадані розмови -Цей callback призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати -розмову, і запускається після завершення core-обробки схвалення. +Цей callback призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати +розмову, і виконується після завершення обробки approval у ядрі. ## Runtime-хуки провайдера -Plugins провайдерів мають три шари: +Plugin провайдерів мають три шари: -- **Метадані маніфесту** для дешевого pre-runtime пошуку: - `setup.providers[].envVars`, застаріла сумісність `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого lookup до runtime: + `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. -- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс +- **Хуки під час конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. - **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють auth, розв’язання моделі, - обгортання stream, рівні thinking, політику replay і usage endpoints. Див. - повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). + обгортання stream, рівні thinking, політику replay і endpoint-и usage. Повний + список див. у розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw усе ще володіє generic agent loop, failover, обробкою transcript і -політикою інструментів. Ці хуки є extension-поверхнею для provider-specific -поведінки без потреби в повністю custom inference transport. +OpenClaw досі володіє загальним циклом агента, failover, обробкою transcript і +політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, +без потреби в повністю власному транспорті inference. -Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має env-based -облікові дані, які generic auth/status/model-picker шляхи мають бачити без -завантаження runtime Plugin. Застарілий `providerAuthEnvVars` все ще читається -адаптером сумісності протягом вікна deprecation, а невбудовані plugins, +Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, +які загальні шляхи auth/status/model-picker мають бачити без +завантаження runtime Plugin. Застарілий `providerAuthEnvVars` усе ще читається +адаптером сумісності протягом вікна припинення підтримки, а невбудовані Plugin, які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, -коли один id провайдера має повторно використовувати env vars іншого id провайдера, auth profiles, -config-backed auth і API-key onboarding choice. Використовуйте маніфест +коли один ідентифікатор провайдера має повторно використовувати env vars, auth profiles, +auth на основі config і варіант onboarding з API-ключем іншого ідентифікатора провайдера. Використовуйте маніфест `providerAuthChoices`, коли onboarding/auth-choice CLI-поверхні мають знати -choice id провайдера, мітки груп і просте one-flag auth wiring без -завантаження runtime провайдера. Зберігайте runtime провайдера -`envVars` для operator-facing підказок, як-от onboarding labels або OAuth -client-id/client-secret setup vars. +ідентифікатор вибору провайдера, мітки груп і просте auth-підключення одним прапорцем без +завантаження runtime провайдера. Залишайте runtime-провайдерські +`envVars` для підказок, видимих оператору, як-от мітки onboarding або змінні налаштування OAuth +client-id/client-secret. -Використовуйте маніфест `channelEnvVars`, коли канал має env-driven auth або налаштування, яке -generic shell-env fallback, перевірки config/status або setup prompts мають бачити +Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, кероване env, яке +загальний fallback shell-env, перевірки config/status або prompts налаштування мають бачити без завантаження runtime каналу. ### Порядок і використання хуків -Для plugins моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. -Стовпець "Коли використовувати" — це короткий посібник для вибору. -Compatibility-only поля провайдера, які OpenClaw більше не викликає, як-от +Для Plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» є коротким посібником із вибору. +Поля провайдера лише для сумісності, які OpenClaw більше не викликає, як-от `ProviderPlugin.capabilities` і `suppressBuiltInModel`, навмисно не перелічені тут. -| # | Хук | Що робить | Коли використовувати | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або стандартними значеннями базового URL | -| 2 | `applyConfigDefaults` | Застосовує глобальні стандартні значення конфігурації, що належать постачальнику, під час матеріалізації конфігурації | Стандартні значення залежать від режиму автентифікації, середовища або семантики сімейства моделей постачальника | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не хук plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview псевдоніми ідентифікаторів моделей перед пошуком | Постачальник володіє очищенням псевдонімів перед канонічним розв’язанням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | Постачальник володіє очищенням транспорту для користувацьких ідентифікаторів постачальників у тому самому транспортному сімействі | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням runtime/постачальника | Постачальнику потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані помічники Google-сімейства також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування нативного використання потокового передавання до постачальників конфігурації | Постачальнику потрібні виправлення метаданих нативного використання потокового передавання, керовані endpoint | -| 7 | `resolveConfigApiKey` | Розв’язує автентифікацію env-marker для постачальників конфігурації перед завантаженням runtime-автентифікації | Постачальник має власне розв’язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований розв’язувач AWS env-marker | -| 8 | `resolveSyntheticAuth` | Виводить локальну/самостійно розміщену або config-backed автентифікацію без збереження відкритого тексту | Постачальник може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать постачальнику; типовий `persistence` — `runtime-only` для CLI/app-owned облікових даних | Постачальник повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh tokens; оголосіть `contracts.externalAuthProviders` у manifest | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілів позаду env/config-backed автентифікації | Постачальник зберігає синтетичні профілі-заповнювачі, які не мають отримувати пріоритет | -| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, що належать постачальнику і ще не є в локальному реєстрі | Постачальник приймає довільні upstream ідентифікатори моделей | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Постачальнику потрібні мережеві метадані перед розв’язанням невідомих ідентифікаторів | -| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований runner використає розв’язану модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує core transport | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для vendor моделей за іншим сумісним транспортом | Постачальник розпізнає власні моделі на proxy transports без перебрання постачальника | -| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Постачальнику потрібне очищення схем транспортного сімейства | -| 16 | `inspectToolSchemas` | Виводить діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження за ключовими словами без навчання core rules, специфічних для постачальника | -| 17 | `resolveReasoningOutputMode` | Вибирає контракт reasoning-output: native або tagged | Постачальнику потрібен tagged reasoning/final output замість native fields | -| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними wrappers опцій stream | Постачальнику потрібні стандартні параметри запиту або очищення параметрів для окремого постачальника | -| 19 | `createStreamFn` | Повністю замінює звичайний stream path користувацьким транспортом | Постачальнику потрібен користувацький wire protocol, а не лише wrapper | -| 20 | `wrapStreamFn` | Stream wrapper після застосування generic wrappers | Постачальнику потрібні wrappers сумісності заголовків/тіла/моделі запиту без користувацького транспорту | -| 21 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного turn | Постачальник хоче, щоб generic transports надсилали provider-native ідентичність turn | -| 22 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику cool-down сесії | Постачальник хоче, щоб generic WS transports налаштовували заголовки сесії або fallback policy | -| 23 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає runtime рядком `apiKey` | Постачальник зберігає додаткові метадані автентифікації й потребує користувацької форми runtime token | -| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких endpoint оновлення або політики refresh-failure | Постачальник не вписується в спільні refreshers `pi-ai` | -| 25 | `buildAuthDoctorHint` | Підказка ремонту, що додається, коли оновлення OAuth завершується невдачею | Постачальнику потрібні власні вказівки з ремонту автентифікації після невдалого оновлення | -| 26 | `matchesContextOverflowError` | Matcher переповнення context-window, що належить постачальнику | Постачальник має raw overflow errors, які generic heuristics пропустили б | -| 27 | `classifyFailoverReason` | Класифікація причини failover, що належить постачальнику | Постачальник може зіставляти raw API/transport errors із rate-limit/overload/etc | -| 28 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul постачальників | Постачальнику потрібне proxy-specific cache TTL gating | -| 29 | `buildMissingAuthMessage` | Заміна generic повідомлення відновлення missing-auth | Постачальнику потрібна provider-specific підказка відновлення missing-auth | -| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після discovery | Постачальнику потрібні синтетичні forward-compat рядки в `models list` і pickers | -| 31 | `resolveThinkingProfile` | Набір рівнів `/think`, display labels і стандартне значення для конкретної моделі | Постачальник надає користувацьку thinking ladder або binary label для вибраних моделей | -| 32 | `isBinaryThinking` | Compatibility hook для перемикача reasoning on/off | Постачальник надає лише binary thinking on/off | -| 33 | `supportsXHighThinking` | Compatibility hook підтримки `xhigh` reasoning | Постачальник хоче `xhigh` лише на підмножині моделей | -| 34 | `resolveDefaultThinkingLevel` | Compatibility hook стандартного рівня `/think` | Постачальник володіє стандартною політикою `/think` для сімейства моделей | -| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів live profile і smoke selection | Постачальник володіє зіставленням preferred-model для live/smoke | -| 36 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime token/key безпосередньо перед inference | Постачальнику потрібен token exchange або короткострокові облікові дані запиту | -| 37 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь статусу | Провайдер потребує власного аналізу токена використання/квоти або інших облікових даних використання | -| 38 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки використання/квоти після визначення автентифікації | Провайдер потребує специфічної для провайдера кінцевої точки використання або аналізатора корисного навантаження | -| 39 | `createEmbeddingProvider` | Створює належний провайдеру адаптер вбудовувань для пам’яті/пошуку | Поведінка вбудовування пам’яті належить Plugin провайдера | -| 40 | `buildReplayPolicy` | Повертає політику повторного відтворення, що керує обробкою транскрипту для провайдера | Провайдер потребує власної політики транскрипту (наприклад, вилучення блоків мислення) | -| 41 | `sanitizeReplayHistory` | Переписує історію повторного відтворення після загального очищення транскрипту | Провайдер потребує специфічних для провайдера переписувань повторного відтворення поза спільними допоміжними засобами Compaction | -| 42 | `validateReplayTurns` | Виконує фінальну перевірку або зміну форми кроків повторного відтворення перед вбудованим виконавцем | Транспорт провайдера потребує суворішої перевірки кроків після загального очищення | -| 43 | `onModelSelected` | Запускає належні провайдеру побічні ефекти після вибору | Провайдер потребує телеметрії або належного провайдеру стану, коли модель стає активною | +| # | Хук | Що робить | Коли використовувати | +| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями базового URL | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, якими володіє провайдер, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, середовища або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не хук Plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або попередні псевдоніми ідентифікаторів моделей перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розв’язанням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для власних ідентифікаторів провайдерів у тому самому транспортному сімействі | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням середовища виконання/провайдера | Провайдер потребує очищення конфігурації, яке має жити з Plugin; вбудовані помічники сімейства Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує переписування сумісності нативного потокового використання до провайдерів конфігурації | Провайдер потребує виправлень метаданих нативного потокового використання, керованих endpoint | +| 7 | `resolveConfigApiKey` | Розв’язує автентифікацію з env-маркером для провайдерів конфігурації перед завантаженням автентифікації середовища виконання | Провайдер має власне розв’язання API-ключа з env-маркером; `amazon-bedrock` також має тут вбудований розв’язувач env-маркера AWS | +| 8 | `resolveSyntheticAuth` | Показує локальну/самостійно розміщену або підтриману конфігурацією автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, якими володіє провайдер; типове `persistence` — `runtime-only` для облікових даних, якими володіють CLI/застосунок | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh-токенів; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених синтетичних заповнювачів профілю за автентифікацією з env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають отримувати пріоритет | +| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, якими володіє провайдер і яких ще немає в локальному реєстрі | Провайдер приймає довільні ідентифікатори upstream-моделей | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдер потребує мережевих метаданих перед розв’язанням невідомих ідентифікаторів | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає розв’язану модель | Провайдер потребує переписувань транспорту, але все ще використовує основний транспорт | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах без перебрання керування провайдером | +| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдер потребує очищення схем транспортного сімейства | +| 16 | `inspectToolSchemas` | Показує діагностику схем, якою володіє провайдер, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера | +| 17 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт виведення міркувань | Провайдер потребує тегованих міркувань/фінального виведення замість нативних полів | +| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдер потребує типових параметрів запиту або очищення параметрів для окремого провайдера | +| 19 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдер потребує власного дротового протоколу, а не лише обгортки | +| 20 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдер потребує обгорток сумісності заголовків/тіла/моделі запиту без власного транспорту | +| 21 | `resolveTransportTurnState` | Додає нативні транспортні заголовки або метадані для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу | +| 22 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або fallback-політику | +| 23 | `formatApiKey` | Форматувач профілю автентифікації: збережений профіль стає рядком `apiKey` середовища виконання | Провайдер зберігає додаткові метадані автентифікації та потребує власної форми токена середовища виконання | +| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики збоїв оновлення | Провайдер не підходить під спільні оновлювачі `pi-ai` | +| 25 | `buildAuthDoctorHint` | Підказка для відновлення, що додається після збою оновлення OAuth | Провайдер потребує власних вказівок з відновлення автентифікації після збою оновлення | +| 26 | `matchesContextOverflowError` | Власний для провайдера matcher переповнення контекстного вікна | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б | +| 27 | `classifyFailoverReason` | Власна для провайдера класифікація причини failover | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | +| 28 | `isCacheTtlEligible` | Політика кешу підказок для proxy/backhaul-провайдерів | Провайдер потребує proxy-специфічного обмеження TTL кешу | +| 29 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення за відсутньої автентифікації | Провайдер потребує специфічної для провайдера підказки відновлення за відсутньої автентифікації | +| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдер потребує синтетичних рядків прямої сумісності в `models list` і засобах вибору | +| 31 | `resolveThinkingProfile` | Набір рівнів `/think` для конкретної моделі, відображувані мітки та типове значення | Провайдер надає власну драбину мислення або бінарну мітку для вибраних моделей | +| 32 | `isBinaryThinking` | Хук сумісності перемикача міркувань увімкнено/вимкнено | Провайдер надає лише бінарне мислення увімкнено/вимкнено | +| 33 | `supportsXHighThinking` | Хук сумісності підтримки міркувань `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | +| 34 | `resolveDefaultThinkingLevel` | Хук сумісності типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів живого профілю та вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 36 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдер потребує обміну токена або короткоживучих облікових даних запиту | +| 37 | `resolveUsageAuth` | Вирішує облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання | +| 38 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки використання/квот після вирішення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження | +| 39 | `createEmbeddingProvider` | Створює адаптер embedding, яким володіє провайдер, для пам’яті/пошуку | Поведінка embedding пам’яті належить Plugin провайдера | +| 40 | `buildReplayPolicy` | Повертає політику відтворення, яка керує обробкою транскрипта для провайдера | Провайдеру потрібна власна політика транскрипта (наприклад, видалення блоків міркування) | +| 41 | `sanitizeReplayHistory` | Переписує історію відтворення після загального очищення транскрипта | Провайдеру потрібні специфічні для провайдера перезаписи відтворення поза межами спільних допоміжних засобів Compaction | +| 42 | `validateReplayTurns` | Виконує фінальну перевірку або зміну форми ходів відтворення перед вбудованим runner | Транспорт провайдера потребує суворішої перевірки ходів після загальної санітизації | +| 43 | `onModelSelected` | Виконує побічні ефекти після вибору, якими володіє провайдер | Провайдеру потрібна телеметрія або стан, яким володіє провайдер, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спершу перевіряють -зіставлений provider Plugin, а потім переходять до інших provider Plugin-ів із -підтримкою hook-ів, доки один із них фактично не змінить ідентифікатор моделі -або transport/config. Це зберігає роботу alias/compat provider shim-ів без -вимоги, щоб викликач знав, якому bundled Plugin належить перезапис. Якщо жоден -provider hook не перезаписує підтримуваний запис конфігурації Google-сімейства, -bundled нормалізатор конфігурації Google все одно застосовує це очищення +відповідний плагін постачальника, а потім переходять до інших плагінів +постачальників із підтримкою хуків, доки один із них фактично не змінить +ідентифікатор моделі або транспорт/config. Це зберігає роботу +shim-обгорток постачальників для alias/compat, не вимагаючи від викликача знати, +який вбудований плагін відповідає за переписування. Якщо жоден хук +постачальника не переписує підтримуваний запис конфігурації сімейства Google, +вбудований нормалізатор конфігурації Google усе одно застосовує це очищення сумісності. -Якщо provider потребує повністю власного wire protocol або власного request executor, -це інший клас розширення. Ці hook-и призначені для поведінки provider-а, яка -все ще працює у звичайному inference loop OpenClaw. +Якщо постачальнику потрібен повністю власний wire-протокол або власний виконавець +запитів, це інший клас розширення. Ці хуки призначені для поведінки +постачальника, яка й далі працює у звичайному циклі інференсу OpenClaw. -### Приклад provider-а +### Приклад постачальника ```ts api.registerProvider({ @@ -368,45 +367,46 @@ api.registerProvider({ ### Вбудовані приклади -Bundled provider Plugin-и поєднують наведені вище hook-и, щоб адаптуватися до -catalog, auth, thinking, replay і usage-потреб кожного постачальника. Авторитетний -набір hook-ів зберігається з кожним Plugin у `extensions/`; ця сторінка ілюструє -форми, а не дублює список. +Вбудовані плагіни постачальників поєднують наведені вище хуки, щоб відповідати +потребам каталогу, автентифікації, мислення, replay та usage кожного +постачальника. Авторитетний набір хуків розміщений разом із кожним плагіном у +`extensions/`; ця сторінка ілюструє форми, а не дублює список. - - OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із - `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати - upstream ідентифікатори моделей раніше за статичний catalog OpenClaw. + + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` плюс + `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати upstream + ідентифікатори моделей раніше за статичний каталог OpenClaw. - + GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` із `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`. + `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають provider-ам змогу - підключатися до політики transcript через `buildReplayPolicy`, а не - повторно реалізовувати очищення в кожному Plugin. + `anthropic-by-model`, `hybrid-anthropic-openai`) дають постачальникам змогу + підключатися до політики транскриптів через `buildReplayPolicy`, замість + того щоб кожен плагін повторно реалізовував очищення. - + `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і використовують спільний inference loop. + `volcengine` реєструють лише `catalog` і використовують спільний цикл + інференсу. - - Beta headers, `/fast` / `serviceTier` і `context1m` живуть у публічному seam - `api.ts` / `contract-api.ts` Anthropic Plugin + + Beta-заголовки, `/fast` / `serviceTier` і `context1m` містяться у + публічному seam `api.ts` / `contract-api.ts` плагіна Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. -## Допоміжні засоби runtime +## Runtime-помічники -Plugin-и можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних core-помічників через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -425,16 +425,16 @@ const voices = await api.runtime.tts.listVoices({ }); ``` -Нотатки: +Примітки: -- `textToSpeech` повертає звичайний core payload виводу TTS для поверхонь file/voice-note. -- Використовує core-конфігурацію `messages.tts` і вибір provider-а. -- Повертає PCM audio buffer + sample rate. Plugin-и мають виконувати resample/encode для provider-ів. -- `listVoices` є необов'язковим для кожного provider-а. Використовуйте його для voice picker-ів або setup flow-ів, якими володіє постачальник. -- Списки голосів можуть містити багатші metadata, як-от locale, gender і personality tags для picker-ів, обізнаних про provider-а. -- OpenAI та ElevenLabs наразі підтримують telephony. Microsoft не підтримує. +- `textToSpeech` повертає звичайний core payload виходу TTS для поверхонь файлів/голосових нотаток. +- Використовує core-конфігурацію `messages.tts` і вибір постачальника. +- Повертає PCM audio buffer + sample rate. Плагіни мають виконати resample/encode для постачальників. +- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для керованих постачальником voice pickers або setup flows. +- Списки голосів можуть містити багатші метадані, як-от locale, gender і personality tags для picker-ів, обізнаних про постачальника. +- OpenAI та ElevenLabs сьогодні підтримують телефонію. Microsoft не підтримує. -Plugin-и також можуть реєструвати speech provider-ів через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -452,17 +452,17 @@ api.registerSpeechProvider({ }); ``` -Нотатки: +Примітки: -- Тримайте політику TTS, fallback і доставку відповіді в core. -- Використовуйте speech provider-ів для поведінки синтезу, якою володіє постачальник. -- Legacy вхід Microsoft `edge` нормалізується до provider id `microsoft`. -- Бажана модель володіння орієнтована на компанію: один vendor Plugin може володіти - provider-ами тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додає ці +- Тримайте політику TTS, fallback і доставлення відповіді в core. +- Використовуйте постачальників мовлення для поведінки синтезу, що належить постачальнику. +- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`. +- Бажана модель володіння орієнтована на компанію: один плагін постачальника може володіти + текстовими, мовленнєвими, зображувальними та майбутніми медіапостачальниками, коли OpenClaw додає ці capability contracts. -Для розуміння image/audio/video Plugin-и реєструють один типізований -media-understanding provider замість generic key/value bag: +Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого +постачальника media-understanding замість generic key/value bag: ```ts api.registerMediaUnderstandingProvider({ @@ -474,18 +474,18 @@ api.registerMediaUnderstandingProvider({ }); ``` -Нотатки: +Примітки: -- Тримайте orchestration, fallback, config і channel wiring у core. -- Тримайте поведінку постачальника в provider Plugin. -- Additive expansion має залишатися типізованим: нові optional methods, нові optional - result fields, нові optional capabilities. -- Video generation уже використовує той самий pattern: +- Тримайте orchestration, fallback, config і wiring каналів у core. +- Тримайте поведінку постачальника в плагіні постачальника. +- Additive expansion має залишатися типізованим: нові необов’язкові методи, нові необов’язкові + поля результату, нові необов’язкові capabilities. +- Генерація відео вже відповідає тому самому шаблону: - core володіє capability contract і runtime helper - - vendor Plugin-и реєструють `api.registerVideoGenerationProvider(...)` - - feature/channel Plugin-и споживають `api.runtime.videoGeneration.*` + - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)` + - плагіни функцій/каналів використовують `api.runtime.videoGeneration.*` -Для media-understanding runtime helpers Plugin-и можуть викликати: +Для runtime-помічників media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -500,8 +500,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для audio transcription Plugin-и можуть використовувати або media-understanding runtime, -або старіший STT alias: +Для транскрипції аудіо плагіни можуть використовувати або runtime +media-understanding, або старіший alias STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -512,15 +512,15 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ }); ``` -Нотатки: +Примітки: - `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для - розуміння image/audio/video. -- Використовує core audio-конфігурацію media-understanding (`tools.media.audio`) і fallback order provider-ів. -- Повертає `{ text: undefined }`, коли transcription output не створено (наприклад, вхід пропущено/не підтримується). -- `api.runtime.stt.transcribeAudioFile(...)` залишається compatibility alias. + розуміння зображень/аудіо/відео. +- Використовує core-конфігурацію аудіо media-understanding (`tools.media.audio`) і fallback order постачальників. +- Повертає `{ text: undefined }`, коли результат транскрипції не створено (наприклад, вхід пропущено/не підтримується). +- `api.runtime.stt.transcribeAudioFile(...)` залишається alias сумісності. -Plugin-и також можуть запускати фонові subagent runs через `api.runtime.subagent`: +Плагіни також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -532,17 +532,17 @@ const result = await api.runtime.subagent.run({ }); ``` -Нотатки: +Примітки: -- `provider` і `model` є optional per-run overrides, а не persistent session changes. -- OpenClaw враховує ці override fields лише для trusted callers. -- Для fallback runs, якими володіє Plugin, operators мають явно ввімкнути `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити trusted Plugin-и конкретними canonical `provider/model` targets, або `"*"`, щоб явно дозволити будь-який target. -- Untrusted plugin subagent runs усе ще працюють, але override requests відхиляються замість мовчазного fallback. -- Створені Plugin subagent sessions позначаються id Plugin, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці owned sessions; довільне видалення session усе ще вимагає admin-scoped Gateway request. +- `provider` і `model` є необов’язковими per-run overrides, а не постійними змінами сесії. +- OpenClaw враховує ці override-поля лише для довірених викликачів. +- Для fallback-виконань, що належать плагіну, оператори мають увімкнути `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Недовірені subagent-виконання плагінів усе ще працюють, але override-запити відхиляються, а не тихо переходять на fallback. +- Створені плагіном subagent-сесії позначаються ідентифікатором плагіна, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці власні сесії; довільне видалення сесії все ще потребує admin-scoped Gateway-запиту. -Для web search Plugin-и можуть використовувати спільний runtime helper замість -доступу до agent tool wiring: +Для вебпошуку плагіни можуть використовувати спільний runtime helper замість +звернення до wiring інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -558,14 +558,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugin-и також можуть реєструвати web-search provider-ів через +Плагіни також можуть реєструвати постачальників вебпошуку через `api.registerWebSearchProvider(...)`. -Нотатки: +Примітки: -- Тримайте вибір provider-а, credential resolution і спільну request semantics у core. -- Використовуйте web-search provider-ів для vendor-specific search transports. -- `api.runtime.webSearch.*` є бажаною спільною поверхнею для feature/channel Plugin-ів, яким потрібна search behavior без залежності від agent tool wrapper. +- Тримайте вибір постачальника, credential resolution і спільну семантику запитів у core. +- Використовуйте постачальників вебпошуку для специфічних для постачальника search transports. +- `api.runtime.webSearch.*` є бажаною спільною поверхнею для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від agent tool wrapper. ### `api.runtime.imageGeneration` @@ -580,12 +580,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка image-generation provider-ів. -- `listProviders(...)`: перелічує доступних image-generation provider-ів та їхні capabilities. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюга постачальників image-generation. +- `listProviders(...)`: перелічує доступних постачальників image-generation та їхні capabilities. ## HTTP-маршрути Gateway -Plugin-и можуть виставляти HTTP endpoints через `api.registerHttpRoute(...)`. +Плагіни можуть надавати HTTP-endpoints через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -602,134 +602,131 @@ api.registerHttpRoute({ Поля маршруту: -- `path`: route path під HTTP server Gateway. -- `auth`: обов'язкове. Використовуйте `"gateway"`, щоб вимагати звичайний gateway auth, або `"plugin"` для plugin-managed auth/webhook verification. -- `match`: необов'язкове. `"exact"` (default) або `"prefix"`. -- `replaceExisting`: необов'язкове. Дозволяє тому самому Plugin замінити власну наявну route registration. -- `handler`: поверніть `true`, коли route обробив request. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну gateway-автентифікацію, або `"plugin"` для керованої плагіном автентифікації/перевірки webhook. +- `match`: необов’язкове. `"exact"` (за замовчуванням) або `"prefix"`. +- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `handler`: повертає `true`, коли маршрут обробив запит. -Нотатки: +Примітки: -- `api.registerHttpHandler(...)` було видалено, і це спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути Plugin мають явно оголошувати `auth`. -- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin. +- `api.registerHttpHandler(...)` було вилучено, і це спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути плагінів мають явно оголошувати `auth`. +- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. - Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюжки переходу `exact`/`prefix` лише на одному рівні auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично runtime-області оператора. Вони призначені для Webhook/перевірки підпису, керованих Plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` виконуються всередині runtime-області запиту Gateway, але ця область навмисно консервативна: - - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує runtime-області маршрутів Plugin прив’язаними до `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад `trusted-proxy` або `gateway.auth.mode = "none"` на приватному вході) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів Plugin з ідентичністю, runtime-область повертається до `operator.write` -- Практичне правило: не вважайте маршрут Plugin з gateway-auth неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- Маршрути `auth: "plugin"` **не** отримують автоматично області дії runtime оператора. Вони призначені для керованих плагіном Webhook або перевірки підписів, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` виконуються всередині області дії runtime запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області дії runtime маршрутів плагіна зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів плагіна з ідентичністю, область дії runtime повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим auth з ідентичністю та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Використовуйте вузькі підшляхи SDK замість монолітного кореневого barrel `openclaw/plugin-sdk` під час створення нових plugins. Основні підшляхи: +Під час створення нових плагінів використовуйте вузькі підшляхи SDK замість монолітного кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: -| Підшлях | Призначення | +| Підшлях | Призначення | | ----------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації плагіна | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/збірки каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт | | `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) | -Канальні plugins вибирають із родини вузьких швів — `channel-setup`, +Плагіни каналів вибирають із сімейства вузьких стиків — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, -`channel-targets` і `channel-actions`. Поведінку підтвердження слід консолідувати +`channel-targets` і `channel-actions`. Поведінку затвердження слід консолідувати на одному контракті `approvalCapability`, а не змішувати між непов’язаними -полями Plugin. Див. [Канальні plugins](/uk/plugins/sdk-channel-plugins). +полями плагіна. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). -Допоміжні засоби runtime і конфігурації розміщені у відповідних сфокусованих підшляхах -`*-runtime` (`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, -`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`, -`channel-activity-runtime` тощо). Надавайте перевагу `config-types`, +Допоміжні засоби runtime та конфігурації містяться у відповідних сфокусованих +підшляхах `*-runtime` (`approval-runtime`, `agent-runtime`, `lazy-runtime`, +`directory-runtime`, `text-runtime`, `runtime-store`, `system-event-runtime`, +`heartbeat-runtime`, `channel-activity-runtime` тощо). Віддавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` замість широкого сумісного barrel `config-runtime`. `openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime` і `openclaw/plugin-sdk/infra-runtime` є застарілими сумісними shim для -старіших plugins. Новий код має імпортувати натомість вужчі загальні примітиви. +старіших плагінів. Новий код має імпортувати натомість вужчі загальні примітиви. -Внутрішні точки входу репозиторію (для кореня кожного вбудованого пакета Plugin): +Внутрішні точки входу репозиторію (для кореня кожного пакета вбудованого плагіна): -- `index.js` — точка входу вбудованого Plugin +- `index.js` — точка входу вбудованого плагіна - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для runtime -- `setup-entry.js` — точка входу setup Plugin +- `setup-entry.js` — точка входу плагіна налаштування -Зовнішні plugins мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета Plugin з core або з іншого Plugin. -Точки входу, завантажені через фасад, надають перевагу активному runtime-знімку -конфігурації, коли він існує, а потім повертаються до розв’язаного файлу -конфігурації на диску. +Зовнішні плагіни мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета плагіна з ядра або з іншого плагіна. +Точки входу, завантажені через фасад, віддають перевагу активному знімку +runtime-конфігурації, коли він існує, а потім повертаються до розв’язаного +файлу конфігурації на диску. Підшляхи для конкретних можливостей, як-от `image-generation`, `media-understanding` -і `speech`, існують, бо вбудовані plugins використовують їх зараз. Вони не є -автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте +і `speech`, існують тому, що вбудовані плагіни використовують їх сьогодні. Вони +не є автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну довідкову сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugins мають володіти канально-специфічними внесками схем -`describeMessageTool(...)` для примітивів, що не є повідомленнями, як-от реакції, -прочитання та опитування. Спільне представлення надсилання має використовувати -загальний контракт `MessagePresentation` замість нативних для провайдера полів -кнопок, компонентів, блоків або карток. -Див. [Представлення повідомлень](/uk/plugins/message-presentation) для контракту, -правил fallback, мапінгу провайдерів і чекліста автора Plugin. +Плагіни мають володіти внесками до схеми `describeMessageTool(...)`, специфічними +для каналу, для примітивів не-повідомлень, як-от реакції, прочитання та опитування. +Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` +замість нативних для провайдера полів кнопок, компонентів, блоків або карток. +Див. [Подання повідомлень](/uk/plugins/message-presentation) щодо контракту, +правил fallback, зіставлення провайдерів і чекліста автора плагіна. -Plugins із можливістю надсилання оголошують, що вони можуть відтворювати через можливості повідомлень: +Плагіни, здатні надсилати, оголошують, що вони можуть відображати через можливості повідомлень: -- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`) +- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`) - `delivery-pin` для запитів закріпленої доставки -Core вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту. -Не відкривайте нативні для провайдера UI escape hatch із загального інструмента -повідомлень. Застарілі допоміжні засоби SDK для legacy нативних схем лишаються -експортованими для наявних сторонніх plugins, але нові plugins не повинні їх -використовувати. +Ядро вирішує, чи відображати подання нативно, чи деградувати його до тексту. +Не відкривайте нативні для провайдера аварійні виходи UI із загального інструмента повідомлень. +Застарілі допоміжні засоби SDK для legacy нативних схем лишаються експортованими для наявних +сторонніх плагінів, але нові плагіни не мають їх використовувати. ## Розв’язання цілі каналу -Канальні plugins мають володіти канально-специфічною семантикою цілей. Тримайте -спільний outbound-хост загальним і використовуйте поверхню messaging adapter -для правил провайдера: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Тримайте +спільний outbound host загальним і використовуйте поверхню адаптера messaging для правил провайдера: -- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль слід - трактувати як `direct`, `group` або `channel` перед пошуком у каталозі. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - має ввід одразу перейти до id-подібного розв’язання замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` є fallback Plugin, коли - core потрібне фінальне розв’язання, що належить провайдеру, після нормалізації - або після промаху в каталозі. +- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль + слід вважати `direct`, `group` або `channel` перед пошуком у каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи + вхідні дані слід одразу спрямувати до розв’язання, схожого на id, замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` є fallback плагіна, коли + ядру потрібне остаточне розв’язання, що належить провайдеру, після нормалізації або після + промаху каталогу. - `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічною для провайдера, після розв’язання цілі. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають - відбуватися перед пошуком peers/groups. -- Використовуйте `looksLikeId` для перевірок "трактувати це як явний/нативний target id". -- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для - провайдера, а не для широкого пошуку в каталозі. -- Тримайте нативні ідентифікатори провайдера, як-от chat ids, thread ids, JIDs, - handles і room ids, всередині значень `target` або специфічних для провайдера - параметрів, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для категорійних рішень, які мають відбуватися до + пошуку peers/groups. +- Використовуйте `looksLikeId` для перевірок "вважати це явним/нативним id цілі". +- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для + широкого пошуку в каталозі. +- Тримайте нативні для провайдера id, як-от chat ids, thread ids, JIDs, handles і room + ids, усередині значень `target` або специфічних для провайдера параметрів, а не в загальних + полях SDK. ## Каталоги на основі конфігурації -Plugins, які виводять записи каталогу з конфігурації, мають тримати цю логіку в -Plugin і повторно використовувати спільні допоміжні засоби з +Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в +плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, як-от: -- DM peers, керовані allowlist -- налаштовані мапи channel/group -- статичні fallback каталогу в межах акаунта +- DM peers на основі allowlist +- налаштовані мапи каналів/груп +- статичні directory fallback, scoped до облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: @@ -738,76 +735,74 @@ Plugin і повторно використовувати спільні доп - допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Канально-специфічна інспекція акаунта та нормалізація id мають залишатися в -реалізації Plugin. +Інспекція облікових записів і нормалізація id, специфічні для каналу, мають залишатися в +реалізації плагіна. ## Каталоги провайдерів -Provider plugins можуть визначати каталоги моделей для inference за допомогою +Плагіни провайдерів можуть визначати каталоги моделей для інференсу за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: - `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдера +- `{ providers }` для кількох записів провайдерів -Використовуйте `catalog`, коли Plugin володіє специфічними для провайдера model ids, -типовими base URL або metadata моделей, обмеженими auth. +Використовуйте `catalog`, коли плагін володіє специфічними для провайдера id моделей, типовими +base URL або метаданими моделей, закритими auth. -`catalog.order` керує тим, коли каталог Plugin зливається відносно вбудованих +`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих неявних провайдерів OpenClaw: -- `simple`: прості провайдери, керовані API-key або env +- `simple`: прості провайдери з API-key або з env - `profile`: провайдери, що з’являються, коли існують auth profiles -- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдера +- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі колізії ключів, тож plugins можуть -навмисно перевизначити вбудований запис провайдера з тим самим provider id. +Пізніші провайдери перемагають у разі колізії ключів, тому плагіни можуть навмисно перевизначати +вбудований запис провайдера з тим самим provider id. Сумісність: -- `discovery` досі працює як legacy alias +- `discovery` досі працює як legacy псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Read-only інспекція каналу +## Read-only інспекція каналів -Якщо ваш Plugin реєструє канал, надавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. +Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це runtime-шлях. Йому дозволено припускати, що - облікові дані повністю матеріалізовані, і швидко завершуватися помилкою, - коли бракує потрібних секретів. +- `resolveAccount(...)` є runtime-шляхом. Йому дозволено припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні. - Read-only шляхи команд, як-от `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, а також потоки - doctor/config repair, не повинні матеріалізувати runtime-облікові дані лише - для опису конфігурації. + `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config + repair, не мають потребувати матеріалізації runtime-облікових даних лише для + опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: -- Повертайте лише описовий стан акаунта. +- Повертайте лише описовий стан облікового запису. - Зберігайте `enabled` і `configured`. -- Додавайте поля джерела/статусу облікових даних, коли це доречно, як-от: +- Додавайте поля джерела/стану облікових даних, коли доречно, як-от: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для звітування про - read-only доступність. Повернення `tokenStatus: "available"` (і відповідного - поля source) достатньо для status-команд. -- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через - SecretRef, але недоступні в поточному шляху команди. +- Не потрібно повертати сирі значення токенів лише для звітування про read-only + доступність. Повернення `tokenStatus: "available"` (і відповідного поля джерела) + достатньо для команд у стилі status. +- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але + недоступні в поточному шляху команди. -Це дає read-only командам змогу повідомляти "налаштовано, але недоступно в цьому -шляху команди" замість аварійного завершення або хибного повідомлення, що акаунт -не налаштований. +Це дає змогу read-only командам повідомляти "налаштовано, але недоступно в цьому шляху +команди" замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштований. -## Пакети packages +## Пакети package packs -Каталог Plugin може містити `package.json` з `openclaw.extensions`: +Каталог плагіна може містити `package.json` з `openclaw.extensions`: ```json { @@ -819,59 +814,58 @@ Provider plugins можуть визначати каталоги моделей } ``` -Кожен entry стає Plugin. Якщо pack перелічує кілька extensions, Plugin id +Кожен запис стає плагіном. Якщо pack містить кілька extensions, id плагіна стає `name/`. -Якщо ваш Plugin імпортує npm deps, встановіть їх у цьому каталозі, щоб +Якщо ваш плагін імпортує npm deps, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Security guardrail: кожен entry `openclaw.extensions` має залишатися всередині -каталогу Plugin після розв’язання symlink. Entries, що виходять за межі -каталогу package, відхиляються. +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна +після розв’язання symlink. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка з безпеки: `openclaw plugins install` встановлює залежності Plugin за -допомогою локального для проєкту `npm install --omit=dev --ignore-scripts` (без -lifecycle scripts, без dev dependencies у runtime), ігноруючи успадковані -глобальні налаштування npm install. Тримайте дерева залежностей Plugin -"pure JS/TS" і уникайте packages, які потребують `postinstall` builds. +Примітка з безпеки: `openclaw plugins install` встановлює залежності плагіна за допомогою +локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, +без dev dependencies під час runtime), ігноруючи успадковані глобальні налаштування npm install. +Тримайте дерева залежностей плагіна "pure JS/TS" і уникайте пакетів, які потребують +`postinstall` builds. -Опційно: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потрібні setup surfaces для вимкненого канального Plugin або -коли канальний Plugin увімкнений, але ще не налаштований, він завантажує -`setupEntry` замість повної точки входу Plugin. Це полегшує запуск і setup, -коли ваша основна точка входу Plugin також підключає tools, hooks або інший -код лише для runtime. +Опціонально: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потрібні поверхні налаштування для вимкненого плагіна каналу або +коли плагін каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повної точки входу плагіна. Це робить запуск і налаштування легшими, +коли основна точка входу вашого плагіна також підключає tools, hooks або інший код +лише для runtime. -Опційно: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може підключити канальний Plugin до того самого шляху `setupEntry` під час -pre-listen фази запуску gateway, навіть коли канал уже налаштований. +Опціонально: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +може включити для плагіна каналу той самий шлях `setupEntry` під час pre-listen +фази запуску gateway, навіть коли канал уже налаштований. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup surface, -яка має існувати до того, як gateway почне слухати. На практиці це означає, що -setup entry має зареєструвати кожну можливість, що належить каналу і від якої -залежить startup, як-от: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup-поверхню, яка має існувати +до того, як gateway почне слухати. На практиці це означає, що setup entry +має зареєструвати кожну можливість, якою володіє канал і від якої залежить startup, як-от: - сама реєстрація каналу - будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати -- будь-які gateway methods, tools або services, які мають існувати в тому самому вікні +- будь-які gateway methods, tools або services, які мають існувати протягом того самого вікна -Якщо ваша повна точка входу все ще володіє будь-якою необхідною startup capability, -не вмикайте цей прапорець. Залиште Plugin на типовій поведінці й дозвольте -OpenClaw завантажувати повну точку входу під час startup. +Якщо ваша повна точка входу досі володіє будь-якою потрібною startup-можливістю, не вмикайте +цей прапорець. Залиште плагін на типовій поведінці й дозвольте OpenClaw завантажити +повну точку входу під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби contract-surface лише -для setup, які core може консультувати до завантаження повного runtime каналу. -Поточна setup promotion surface: +Вбудовані канали також можуть публікувати допоміжні засоби contract-surface лише для налаштування, з якими ядро +може консультуватися до завантаження повного runtime каналу. Поточна поверхня +просування налаштування: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу Plugin. Matrix є поточним вбудованим прикладом: він переносить лише ключі автентифікації/початкового налаштування в іменований підвищений обліковий запис, коли іменовані облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. +Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу Plugin. +Matrix є поточним вбудованим прикладом: він переносить лише ключі автентифікації/початкового завантаження в іменований підвищений обліковий запис, коли іменовані облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. -Ці адаптери setup patch зберігають вбудоване виявлення поверхні контракту лінивим. Час імпорту залишається легким; поверхня підвищення завантажується лише під час першого використання замість повторного входу у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають вбудоване виявлення контрактної поверхні лінивим. Час імпорту залишається легким; поверхня підвищення завантажується лише під час першого використання, а не повторно входить у запуск вбудованого каналу під час імпорту модуля. -Коли ці стартові поверхні містять методи RPC Gateway, тримайте їх на префіксі, специфічному для Plugin. Простори імен адміністрування Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди вирішуються в `operator.admin`, навіть якщо Plugin запитує вужчу область. +Коли ці стартові поверхні містять методи RPC Gateway, тримайте їх на префіксі, специфічному для Plugin. Простори імен адміністрування Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди вирішуються як `operator.admin`, навіть якщо Plugin запитує вужчу область. Приклад: @@ -890,7 +884,7 @@ Core використовує цю поверхню, коли потрібно ### Метадані каталогу каналів -Plugin-и каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` та підказки встановлення через `openclaw.install`. Це зберігає каталог Core вільним від даних. +Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це зберігає каталог core без даних. Приклад: @@ -920,18 +914,18 @@ Plugin-и каналів можуть оголошувати метадані н Корисні поля `openclaw.channel` поза мінімальним прикладом: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначає текст посилання для посилання на документацію +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану +- `docsLabel`: перевизначає текст посилання на документацію - `preferOver`: ідентифікатори Plugin/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування текстом поверхні вибору -- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування -- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, коли встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору +- `markdownCapable`: позначає канал як здатний працювати з markdown для рішень щодо вихідного форматування +- `exposure.configured`: приховати канал із поверхонь списку налаштованих каналів, коли встановлено `false` +- `exposure.setup`: приховати канал з інтерактивних засобів вибору налаштування/конфігурації, коли встановлено `false` +- `exposure.docs`: позначити канал як внутрішній/приватний для навігаційних поверхонь документації - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: підключає канал до стандартного потоку швидкого старту `allowFrom` -- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей оголошення +- `quickstartAllowFrom`: увімкнути канал у стандартний потік швидкого старту `allowFrom` +- `forceAccountBinding`: вимагати явного прив’язування облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надавати перевагу пошуку сеансу під час визначення цілей оголошень OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). Розмістіть JSON-файл в одному з таких місць: @@ -939,17 +933,20 @@ OpenClaw також може об’єднувати **зовнішні ката - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. +Або вкажіть у `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) один чи кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів виставляють нормалізовані факти про джерело встановлення поруч із необробленим блоком `openclaw.install`. Нормалізовані факти визначають, чи є npm spec точною версією або плаваючим селектором, чи наявні очікувані метадані цілісності, і чи також доступний локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібрана назва npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, і коли метадані цілісності npm наявні без дійсного джерела npm. Споживачі мають розглядати `installSource` як додаткове необов’язкове поле, щоб записи, створені вручну, і прокладки каталогу не мусили його синтезувати. Це дає onboarding і діагностиці змогу пояснювати стан площини джерела без імпорту runtime Plugin. +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів надають нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані факти визначають, чи є npm-специфікація точною версією або плаваючим селектором, чи присутні очікувані метадані цілісності, і чи доступний також локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, а також коли метадані цілісності npm присутні без дійсного джерела npm. Споживачі мають розглядати `installSource` як додаткове необов’язкове поле, щоб створені вручну записи й прокладки каталогу не мусили його синтезувати. +Це дає змогу onboarding і діагностиці пояснювати стан площини джерел без імпорту runtime Plugin. -Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` плюс `expectedIntegrity`. Голі назви пакетів і dist-tags усе ще працюють для сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися до закріплених, перевірених за цілісністю встановлень без порушення наявних Plugin-ів. Коли onboarding встановлює з локального шляху каталогу, він записує керований запис індексу Plugin із `source: "path"` і відносним до workspace `sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довготривалій конфігурації. Це зберігає локальні встановлення для розробки видимими для діагностики площини джерела без додавання другої поверхні розкриття необробленого шляху файлової системи. Збережений індекс Plugin `plugins/installs.json` є джерелом істини щодо джерела встановлення й може оновлюватися без завантаження runtime-модулів Plugin. Його мапа `installRecords` є довговічною навіть тоді, коли маніфест Plugin відсутній або недійсний; його масив `plugins` є відновлюваним поданням маніфесту. +Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` плюс `expectedIntegrity`. Голі назви пакетів і dist-tags усе ще працюють для сумісності, але вони показують попередження площини джерел, щоб каталог міг перейти до закріплених встановлень із перевіркою цілісності без ламання наявних Plugin. +Коли onboarding встановлює з локального шляху каталогу, він записує керований запис індексу Plugin із `source: "path"` і відносним до workspace `sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довгоживучу конфігурацію. Це зберігає локальні розробницькі встановлення видимими для діагностики площини джерел без додавання другої сирої поверхні розкриття шляхів файлової системи. Збережений індекс Plugin `plugins/installs.json` є джерелом істини для встановлень і може оновлюватися без завантаження runtime-модулів Plugin. +Його мапа `installRecords` є довговічною, навіть коли маніфест Plugin відсутній або недійсний; його масив `plugins` є відновлюваним поданням маніфестів. -## Plugin-и контекстного рушія +## Plugin рушія контексту -Plugin-и контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly і compaction. Зареєструйте їх зі свого Plugin за допомогою `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій через `plugins.slots.contextEngine`. +Plugin рушія контексту володіють оркестрацією контексту сеансу для приймання, складання й Compaction. Зареєструйте їх зі свого Plugin за допомогою `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому Plugin потрібно замінити або розширити стандартний конвеєр контексту, а не просто додати пошук у пам’яті чи hooks. +Використовуйте це, коли вашому Plugin потрібно замінити або розширити стандартний конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -977,7 +974,7 @@ export default function (api) { } ``` -Фабрика `ctx` виставляє необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час створення. +Фабрика `ctx` надає необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час створення. Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і явно делегуйте його: @@ -1020,37 +1017,37 @@ export default function (api) { Рекомендована послідовність: -1. визначте контракт Core - Вирішіть, якою спільною поведінкою має володіти Core: політика, fallback, злиття конфігурації, життєвий цикл, семантика для каналів і форма runtime helper. +1. визначте контракт core + Вирішіть, якою спільною поведінкою має володіти core: політика, fallback, злиття конфігурації, життєвий цикл, семантика для каналів і форма runtime-помічника. 2. додайте типізовані поверхні реєстрації/runtime Plugin Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть Core + споживачів каналу/функції - Канали й Plugin-и функцій мають споживати нову можливість через Core, а не імпортувати реалізацію постачальника напряму. +3. під’єднайте core і споживачів каналів/функцій + Канали та функціональні Plugin мають споживати нову можливість через core, а не імпортувати реалізацію постачальника напряму. 4. зареєструйте реалізації постачальників - Потім Plugin-и постачальників реєструють свої бекенди для цієї можливості. -5. додайте покриття контракту - Додайте тести, щоб форма володіння та реєстрації з часом залишалася явною. + Plugin постачальників потім реєструють свої бекенди для цієї можливості. +5. додайте контрактне покриття + Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною. -Так OpenClaw залишається принциповим, не стаючи жорстко закодованим під світогляд одного провайдера. Див. [Кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного контрольного списку файлів і опрацьованого прикладу. +Так OpenClaw залишається принциповим, не стаючи жорстко прив’язаним до світогляду одного провайдера. Дивіться [Кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного чекліста файлів і пропрацьованого прикладу. -### Контрольний список можливості +### Чекліст можливості Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих поверхонь разом: -- типи контракту Core в `src//types.ts` -- runner/runtime helper Core в `src//runtime.ts` +- типи контракту core в `src//types.ts` +- runner/runtime-помічник core в `src//runtime.ts` - поверхня реєстрації API Plugin в `src/plugins/types.ts` -- підключення реєстру Plugin в `src/plugins/registry.ts` -- runtime-експозиція Plugin у `src/plugins/runtime/*`, коли Plugin-и функцій/каналів мають її споживати -- helpers для capture/test у `src/test-utils/plugin-registration.ts` -- твердження про володіння/контракт у `src/plugins/contracts/registry.ts` -- документація для operator/Plugin у `docs/` +- під’єднання реєстру Plugin в `src/plugins/registry.ts` +- експонування runtime Plugin в `src/plugins/runtime/*`, коли функціональні/канальні Plugin мають його споживати +- помічники захоплення/тестування в `src/test-utils/plugin-registration.ts` +- твердження володіння/контракту в `src/plugins/contracts/registry.ts` +- документація оператора/Plugin в `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака, що можливість ще не повністю інтегрована. +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості -Мінімальний патерн: +Мінімальний шаблон: ```ts // core contract @@ -1076,7 +1073,7 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Патерн контрактного тесту: +Шаблон контрактного тесту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1084,14 +1081,14 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- Core володіє контрактом можливості + оркестрацією -- Plugin-и постачальників володіють реалізаціями постачальників -- Plugin-и функцій/каналів споживають runtime helpers +- core володіє контрактом можливості й оркестрацією +- Plugin постачальників володіють реалізаціями постачальників +- функціональні/канальні Plugin споживають runtime-помічники - контрактні тести зберігають володіння явним ## Пов’язане - [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми -- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) -- [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugin-ів](/uk/plugins/building-plugins) +- [Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths) +- [Налаштування SDK Plugin](/uk/plugins/sdk-setup) +- [Побудова Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/compatibility.md b/docs/uk/plugins/compatibility.md index 52a4318fb..8798a90e6 100644 --- a/docs/uk/plugins/compatibility.md +++ b/docs/uk/plugins/compatibility.md @@ -2,45 +2,45 @@ read_when: - Ви підтримуєте OpenClaw Plugin - Ви бачите попередження про сумісність Plugin - - Ви плануєте міграцію SDK Plugin або маніфесту -summary: Контракти сумісності Plugin, метадані про застарівання та очікування щодо міграції + - Ви плануєте міграцію SDK для Plugin або маніфесту +summary: Контракти сумісності Plugin, метадані застарівання та очікування щодо міграції title: Сумісність Plugin x-i18n: - generated_at: "2026-04-28T11:18:59Z" + generated_at: "2026-05-01T22:03:46Z" model: gpt-5.5 provider: openai - source_hash: 344dbaac86db7259adc09bc91b7fbe7ba540fc6fdd96cc422918ccf2c34d9cec + source_hash: eecf94743cf34c5b773bfa8066164f90b7c8a75667c43f3f1002d32ec1d04902 source_path: plugins/compatibility.md workflow: 16 --- -OpenClaw зберігає старіші контракти plugin підключеними через іменовані адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані та зовнішні plugins, поки контракти SDK, маніфесту, налаштування, конфігурації та runtime агентів еволюціонують. +OpenClaw зберігає старіші контракти плагінів під’єднаними через іменовані адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані та зовнішні плагіни, поки розвиваються контракти SDK, маніфесту, налаштування, конфігурації та середовища виконання агента. ## Реєстр сумісності -Контракти сумісності plugin відстежуються в основному реєстрі за адресою +Контракти сумісності плагінів відстежуються в основному реєстрі за адресою `src/plugins/compat/registry.ts`. Кожен запис має: - стабільний код сумісності - статус: `active`, `deprecated`, `removal-pending` або `removed` -- власник: SDK, конфігурація, налаштування, канал, провайдер, виконання plugin, runtime агента +- власника: SDK, конфігурація, налаштування, канал, провайдер, виконання плагіна, середовище виконання агента або ядро -- дати впровадження та застарівання, коли застосовно +- дати запровадження та виведення з ужитку, коли застосовно - рекомендації щодо заміни -- документація, діагностика та тести, які охоплюють стару й нову поведінку +- документацію, діагностику та тести, які покривають стару й нову поведінку -Реєстр є джерелом для планування супроводу та майбутніх перевірок інспектора plugin. Якщо поведінка, видима для plugin, змінюється, додайте або оновіть запис сумісності в тій самій зміні, яка додає адаптер. +Реєстр є джерелом для планування супроводу та майбутніх перевірок інспектора плагінів. Якщо поведінка, видима плагінам, змінюється, додайте або оновіть запис сумісності в тій самій зміні, яка додає адаптер. Сумісність виправлень Doctor і міграцій відстежується окремо за адресою -`src/commands/doctor/shared/deprecation-compat.ts`. Ці записи охоплюють старі форми конфігурації, макети журналу встановлень і допоміжні модулі виправлення, які можуть потребувати збереження доступності після видалення runtime-шляху сумісності. +`src/commands/doctor/shared/deprecation-compat.ts`. Ці записи покривають старі форми конфігурації, структури журналу встановлень і сумісні прошарки для виправлень, які можуть мати залишатися доступними після видалення шляху сумісності середовища виконання. -Релізні перевірки мають перевіряти обидва реєстри. Не видаляйте міграцію Doctor лише тому, що відповідний runtime-запис або запис сумісності конфігурації завершився; спочатку перевірте, що немає підтримуваного шляху оновлення, якому все ще потрібне виправлення. Також повторно перевіряйте кожну анотацію заміни під час планування релізу, оскільки володіння plugin і конфігураційний footprint можуть змінюватися, коли провайдери та канали переміщуються з ядра. +Релізні перевірки мають перевіряти обидва реєстри. Не видаляйте міграцію Doctor лише тому, що відповідний запис сумісності середовища виконання або конфігурації застарів; спершу переконайтеся, що немає підтримуваного шляху оновлення, якому досі потрібне це виправлення. Також повторно перевіряйте кожну анотацію заміни під час планування релізу, бо власність плагінів і конфігураційний слід можуть змінюватися, коли провайдери та канали переміщуються з ядра. -## Пакет інспектора plugin +## Пакет інспектора плагінів -Інспектор plugin має жити поза основним репозиторієм OpenClaw як окремий пакет/репозиторій, що спирається на версіоновані контракти сумісності та маніфесту. +Інспектор плагінів має жити поза основним репозиторієм OpenClaw як окремий пакет/репозиторій, що спирається на версіоновані контракти сумісності та маніфесту. CLI першого дня має бути: @@ -50,17 +50,17 @@ openclaw-plugin-inspector ./my-plugin Він має виводити: -- перевірку маніфесту/схеми +- валідацію маніфесту/схеми - версію сумісності контракту, що перевіряється - перевірки метаданих встановлення/джерела - перевірки імпортів холодного шляху -- попередження про застарівання та сумісність +- попередження про виведення з ужитку та сумісність -Використовуйте `--json` для стабільного машинозчитуваного виводу в анотаціях CI. Ядро OpenClaw має надавати контракти й фікстури, які інспектор може споживати, але не має публікувати бінарник інспектора з основного пакета `openclaw`. +Використовуйте `--json` для стабільного машинозчитуваного виводу в анотаціях CI. Ядро OpenClaw має надавати контракти й фікстури, які може споживати інспектор, але не має публікувати двійковий файл інспектора з основного пакета `openclaw`. -### Смуга приймання для супровідників +### Лінія приймання для супровідників -Використовуйте Blacksmith Testbox для смуги приймання встановлюваного пакета під час перевірки зовнішнього інспектора на пакетах plugin OpenClaw. Запускайте його з чистого checkout OpenClaw після збирання пакета: +Використовуйте Blacksmith Testbox для лінії приймання встановлюваного пакета під час валідації зовнішнього інспектора з пакетами плагінів OpenClaw. Запускайте її з чистого checkout OpenClaw після збирання пакета: ```sh blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 @@ -70,21 +70,21 @@ blacksmith testbox run --id "npm exec --yes @openclaw/plugin-inspector@ blacksmith testbox stop ``` -Залишайте цю смугу opt-in для супровідників, оскільки вона встановлює зовнішній npm-пакет і може перевіряти пакети plugin, клоновані поза репозиторієм. Локальні захисти репозиторію охоплюють мапу експорту SDK, метадані реєстру сумісності, скорочення застарілих імпортів SDK і межі імпортів вбудованих extensions; доказ інспектора в Testbox охоплює пакет так, як його споживають автори зовнішніх plugin. +Залишайте цю лінію опційною для супровідників, бо вона встановлює зовнішній npm-пакет і може перевіряти пакети плагінів, клоновані поза репозиторієм. Локальні запобіжники репозиторію покривають мапу експорту SDK, метадані реєстру сумісності, скорочення застарілих SDK-імпортів і межі імпорту вбудованих розширень; підтвердження інспектора в Testbox покриває пакет так, як його споживають автори зовнішніх плагінів. -## Політика застарівання +## Політика виведення з ужитку -OpenClaw не має видаляти задокументований контракт plugin у тому самому релізі, який вводить його заміну. +OpenClaw не має видаляти задокументований контракт плагіна в тому самому релізі, який вводить його заміну. -Послідовність міграції: +Послідовність міграції така: 1. Додайте новий контракт. -2. Залиште стару поведінку підключеною через іменований адаптер сумісності. -3. Виводьте діагностику або попередження, коли автори plugin можуть діяти. -4. Задокументуйте заміну та timeline. -5. Тестуйте старий і новий шляхи. -6. Зачекайте протягом оголошеного вікна міграції. -7. Видаляйте лише з явним схваленням breaking-релізу. +2. Залиште стару поведінку під’єднаною через іменований адаптер сумісності. +3. Виводьте діагностику або попередження, коли автори плагінів можуть діяти. +4. Задокументуйте заміну й графік. +5. Протестуйте старий і новий шляхи. +6. Дочекайтеся завершення оголошеного вікна міграції. +7. Видаляйте лише з явним схваленням для релізу з несумісними змінами. Застарілі записи мають містити дату початку попереджень, заміну, посилання на документацію та фінальну дату видалення не пізніше ніж через три місяці після початку попереджень. Не додавайте застарілий шлях сумісності з відкритим вікном видалення, якщо супровідники явно не вирішили, що це постійна сумісність, і не позначили його як `active`. @@ -92,52 +92,49 @@ OpenClaw не має видаляти задокументований конт Поточні записи сумісності включають: -- застарілі широкі імпорти SDK, такі як `openclaw/plugin-sdk/compat` -- застарілі форми plugin лише з хуками та `before_agent_start` -- застарілі entrypoints plugin `activate(api)`, поки plugins мігрують на +- старі широкі імпорти SDK, як-от `openclaw/plugin-sdk/compat` +- старі форми плагінів лише з hooks і `before_agent_start` +- старі точки входу плагінів `activate(api)`, поки плагіни мігрують на `register(api)` -- застарілі псевдоніми SDK, такі як `openclaw/extension-api`, - `openclaw/plugin-sdk/channel-runtime`, білдери статусів `openclaw/plugin-sdk/command-auth`, - `openclaw/plugin-sdk/test-utils` (замінено на сфокусовані тестові підшляхи +- старі псевдоніми SDK, як-от `openclaw/extension-api`, + `openclaw/plugin-sdk/channel-runtime`, побудовники статусу `openclaw/plugin-sdk/command-auth`, + `openclaw/plugin-sdk/test-utils` (замінено цільовими тестовими підшляхами `openclaw/plugin-sdk/*`) і псевдоніми типів `ClawdbotConfig` / `OpenClawSchemaType` -- allowlist вбудованих plugin і поведінку ввімкнення -- застарілі метадані маніфесту env-var провайдерів/каналів -- застарілі хуки plugin провайдерів і псевдоніми типів, поки провайдери переходять на - явні хуки каталогу, авторизації, thinking, replay і транспорту -- застарілі runtime-псевдоніми, такі як `api.runtime.taskFlow`, +- allowlist вбудованих плагінів і поведінку ввімкнення +- старі метадані маніфесту env-var для провайдерів/каналів +- старі hooks плагінів провайдерів і псевдоніми типів, поки провайдери переходять на + явні hooks каталогу, автентифікації, thinking, replay і транспорту +- старі псевдоніми середовища виконання, як-от `api.runtime.taskFlow`, `api.runtime.subagent.getSession`, `api.runtime.stt` і застарілі `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` -- застарілу розділену реєстрацію memory-plugin, поки memory plugins переходять на +- стару розділену реєстрацію memory-плагінів, поки memory-плагіни переходять на `registerMemoryCapability` -- застарілі допоміжні модулі SDK каналу для нативних схем повідомлень, mention gating, - форматування вхідного envelope і вкладення approval capability -- застарілі псевдоніми ключа маршруту каналу та helper для comparable-target, поки plugins +- старі допоміжні засоби SDK каналів для нативних схем повідомлень, обмеження mentions, + форматування вхідного конверта та вкладення можливостей схвалення +- старий ключ маршруту каналу та псевдоніми допоміжних засобів comparable-target, поки плагіни переходять на `openclaw/plugin-sdk/channel-route` -- activation hints, які замінюються володінням внесками маніфесту -- застаріле неявне завантаження sidecar під час старту для plugins, які не оголосили - `activation.onStartup`; супровідники можуть тестувати майбутню суворішу поведінку з - `OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1` -- runtime fallback `setup-api`, поки дескриптори налаштування переходять на холодні +- підказки активації, які замінюються власністю внесків маніфесту +- fallback середовища виконання `setup-api`, поки дескриптори налаштування переходять на холодні метадані `setup.requiresRuntime: false` -- хуки `discovery` провайдера, поки хуки каталогу провайдера переходять на +- hooks `discovery` провайдерів, поки hooks каталогу провайдерів переходять на `catalog.run(...)` -- метадані каналу `showConfigured` / `showInSetup`, поки пакети каналів переходять +- метадані каналів `showConfigured` / `showInSetup`, поки пакети каналів переходять на `openclaw.channel.exposure` -- застарілі ключі конфігурації runtime-policy, поки Doctor мігрує операторів на +- старі ключі конфігурації runtime-policy, поки Doctor мігрує операторів на `agentRuntime` -- fallback згенерованих метаданих конфігурації вбудованого каналу, поки впроваджуються registry-first +- fallback згенерованих метаданих конфігурації вбудованих каналів, поки з’являються registry-first метадані `channelConfigs` -- збережені env-прапорці вимкнення реєстру plugin і install-migration, поки +- збережені env-прапори вимкнення реєстру плагінів і міграції встановлень, поки потоки виправлення мігрують операторів на `openclaw plugins registry --refresh` і `openclaw doctor --fix` -- застарілі шляхи конфігурації вебпошуку, web fetch і x_search, якими володіє plugin, поки - Doctor мігрує їх до `plugins.entries..config` -- застарілу створену автором конфігурацію `plugins.installs` і псевдоніми load-path вбудованих plugin, - поки метадані встановлення переходять у керований станом журнал plugin +- старі шляхи конфігурації вебпошуку, веботримання та x_search, що належать плагінам, поки + Doctor мігрує їх у `plugins.entries..config` +- старі авторські конфігурації `plugins.installs` і псевдоніми шляхів завантаження вбудованих плагінів, + поки метадані встановлення переміщуються в керований станом журнал плагінів -Новий код plugin має надавати перевагу заміні, зазначеній у реєстрі та в конкретному посібнику з міграції. Наявні plugins можуть продовжувати використовувати шлях сумісності, доки документація, діагностика та примітки до релізу не оголосять вікно видалення. +Новий код плагінів має віддавати перевагу заміні, зазначеній у реєстрі та в конкретному посібнику з міграції. Наявні плагіни можуть продовжувати використовувати шлях сумісності, доки документація, діагностика та нотатки до релізу не оголосять вікно видалення. -## Примітки до релізу +## Нотатки до релізу -Примітки до релізу мають включати майбутні застарівання plugin із цільовими датами та посиланнями на документацію з міграції. Це попередження має відбутися до того, як шлях сумісності перейде до `removal-pending` або `removed`. +Нотатки до релізу мають включати майбутні виведення з ужитку для плагінів із цільовими датами та посиланнями на документацію з міграції. Це попередження має з’явитися до того, як шлях сумісності перейде в `removal-pending` або `removed`. diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 43b6fcf2e..ac5b5a79a 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,64 @@ --- read_when: - Ви створюєте Plugin для OpenClaw - - Потрібно випустити схему конфігурації Plugin або налагодити помилки валідації Plugin -summary: Маніфест Plugin + вимоги до схеми JSON (сувора перевірка конфігурації) + - Вам потрібно випустити схему конфігурації Plugin або усунути помилки валідації Plugin +summary: Plugin manifest + вимоги до схеми JSON (сувора перевірка конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-05-01T21:40:22Z" + generated_at: "2026-05-01T22:03:37Z" model: gpt-5.5 provider: openai - source_hash: cb611c247a395ad03bef21fe5cf801f66f4529980521996ddda11453b5a0eab2 + source_hash: 19eb639d3a511c7be916764abdb179c6d3c126968f640836686cd2250950c795 source_path: plugins/manifest.md workflow: 16 --- Ця сторінка стосується лише **нативного маніфесту 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.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета та оголошені +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені Skills, корені команд Claude, стандартні значення `settings.json` пакета Claude, -стандартні значення LSP пакета Claude та підтримувані набори hooks, коли макет відповідає -очікуванням runtime OpenClaw. +стандартні значення LSP пакета Claude і підтримувані набори хуків, коли макет відповідає +очікуванням середовища виконання OpenClaw. -Кожен нативний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у +Кожен нативний 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**. Усе нижче має бути достатньо дешевим для перевірки без запуску -runtime Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження вашого +коду Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску +середовища виконання Plugin. **Використовуйте його для:** -- ідентичності Plugin, перевірки конфігурації та підказок UI конфігурації -- метаданих автентифікації, onboarding і налаштування (псевдонім, автоматичне ввімкнення, env vars провайдера, варіанти автентифікації) -- підказок активації для поверхонь control plane +- ідентифікації Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації +- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь площини керування - скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти +- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` - метаданих конфігурації для конкретного каналу, об’єднаних у каталог і поверхні перевірки -**Не використовуйте його для:** реєстрації поведінки runtime, оголошення точок входу коду -або метаданих встановлення npm. Вони належать до коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення точок входу коду +або метаданих встановлення npm. Вони належать до вашого коду Plugin і `package.json`. ## Мінімальний приклад @@ -73,7 +73,7 @@ runtime Plugin. } ``` -## Розширений приклад +## Розгорнутий приклад ```json { @@ -152,74 +152,74 @@ runtime Plugin. ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що означає | -| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений за замовчуванням. Опустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб лишити plugin вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей plugin, коли auth, config або посилання на модель згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, що належать цьому plugin. Використовується для виявлення та перевірки конфігурації. | -| `providers` | Ні | `string[]` | Id провайдерів, що належать цьому plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легкого модуля виявлення провайдера, відносно кореня plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, які використовуються для автоматичного завантаження plugin перед runtime. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, що належать цьому plugin. Це контракт control-plane для майбутнього read-only спискування, onboarding, вибору моделей, псевдонімів і приглушення без завантаження runtime plugin. | -| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, що належить провайдеру. Використовуйте її, щоб виключити локальних/self-hosted провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з id каталогів OpenRouter/LiteLLM без жорсткого кодування id провайдерів у core. | -| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів id моделей, що належить провайдеру й має виконуватися до завантаження runtime провайдера. | -| `providerEndpoints` | Ні | `object[]` | Метадані endpoint host/baseUrl, що належать маніфесту, для маршрутів провайдерів, які core має класифікувати до завантаження runtime провайдера. | -| `providerRequest` | Ні | `object` | Дешеві метадані сімейства провайдерів і сумісності запитів, які використовуються загальною політикою запитів до завантаження runtime провайдера. | -| `cliBackends` | Ні | `string[]` | Id backend CLI inference, що належать цьому plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких synthetic auth hook, що належить plugin, має перевірятися під час cold model discovery до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать bundled plugin і представляють несекретний локальний, OAuth або ambient credential стан. | -| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому plugin і мають створювати plugin-aware діагностику конфігурації та CLI до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні env-метадані для пошуку auth/status провайдера. Для нових plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час періоду вилучення. | -| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для auth lookup, наприклад coding provider, що спільно використовує API key базового провайдера й auth profiles. | -| `channelEnvVars` | Ні | `Record` | Дешеві env-метадані каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для env-driven налаштування каналу або auth surfaces, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані auth-choice для onboarding pickers, preferred-provider resolution і простого wiring прапорів CLI. | -| `activation` | Ні | `object` | Дешеві метадані планувальника активації для startup, provider, command, channel, route і capability-triggered loading. Лише метадані; runtime plugin усе ще відповідає за фактичну поведінку. | -| `setup` | Ні | `object` | Дешеві дескриптори setup/onboarding, які discovery та setup surfaces можуть перевіряти без завантаження runtime plugin. | -| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, які використовуються спільним host `openclaw qa` до завантаження runtime plugin. | -| `contracts` | Ні | `object` | Статичний snapshot bundled capability для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві media-understanding defaults для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються з discovery та validation surfaces до завантаження runtime. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Зручна для читання назва plugin. | -| `description` | Ні | `string` | Короткий підсумок, що показується на plugin surfaces. | -| `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholder-и та підказки чутливості для полів конфігурації. | +| Поле | Обов’язково | Тип | Що це означає | +| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли auth, config або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, що належать цьому плагіну. Використовується для виявлення та перевірки конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, що належать цьому плагіну. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдерів, відносний до кореня плагіна, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime плагіна. | +| `modelSupport` | Ні | `object` | Скорочені метадані родин моделей, що належать маніфесту та використовуються для автоматичного завантаження плагіна перед runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, що належать цьому плагіну. Це контракт площини керування для майбутнього списку лише для читання, onboarding, засобів вибору моделей, псевдонімів і придушення без завантаження runtime плагіна. | +| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, що належить провайдеру. Використовуйте її, щоб виключити локальних або self-hosted провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у core. | +| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів ідентифікаторів моделей, що належить провайдеру та має виконуватися до завантаження runtime провайдера. | +| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl endpoint, що належать маніфесту, для маршрутів провайдерів, які core має класифікувати до завантаження runtime провайдера. | +| `providerRequest` | Ні | `object` | Дешеві метадані родини провайдера та сумісності запитів, які використовуються загальною політикою запитів до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, що належать цьому плагіну. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких синтетичний auth hook, що належить плагіну, має перевірятися під час холодного виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому плагіну та представляють несекретний локальний, OAuth або ambient credential state. | +| `commandAliases` | Ні | `object[]` | Назви команд, що належать цьому плагіну та мають створювати діагностику конфігурації й CLI з урахуванням плагіна до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі метадані сумісності env для пошуку auth/status провайдера. Для нових плагінів надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом періоду виведення з ужитку. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для auth lookup, наприклад coding provider, що спільно використовує API key базового провайдера та auth profiles. | +| `channelEnvVars` | Ні | `Record` | Дешеві метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або auth surfaces, які мають бачити загальні startup/config helpers. | +| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані вибору auth для onboarding pickers, preferred-provider resolution і простого підключення CLI flags. | +| `activation` | Ні | `object` | Дешеві метадані планувальника активації для startup, provider, command, channel, route і завантаження, спричиненого capability. Лише метадані; runtime плагіна все ще володіє фактичною поведінкою. | +| `setup` | Ні | `object` | Дешеві дескриптори setup/onboarding, які поверхні discovery і setup можуть перевіряти без завантаження runtime плагіна. | +| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, які використовуються спільним host `openclaw qa` до завантаження runtime плагіна. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві стандартні значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту та об’єднуються з поверхнями discovery і validation до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | +| `name` | Ні | `string` | Людиночитна назва плагіна. | +| `description` | Ні | `string` | Короткий підсумок, що показується в поверхнях плагіна. | +| `version` | Ні | `string` | Інформаційна версія плагіна. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | -## Довідник providerAuthChoices +## Довідка `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант onboarding або auth. +Кожен запис `providerAuthChoices` описує один вибір onboarding або auth. OpenClaw читає це до завантаження runtime провайдера. -Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти setup, -отримані з дескрипторів, і метадані install-catalog без завантаження runtime провайдера. +Списки setup провайдера використовують ці вибори з маніфесту, вибори setup, +похідні від дескрипторів, і метадані install-catalog без завантаження runtime провайдера. -| Поле | Обов’язкове | Тип | Що це означає | -| -------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `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"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `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` | Мітка цієї групи, видима користувачу. | +| `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"]`. | -## Довідник commandAliases +## Довідка з commandAliases -Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть +Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту runtime-коду Plugin. +використовує ці метадані для діагностики без імпорту runtime-коду plugin. ```json { @@ -233,53 +233,44 @@ OpenClaw читає це до завантаження runtime провайде } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ----------- | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку варто запропонувати для операцій CLI, якщо така існує. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------- | ----------- | ----------------- | --------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо така існує. | -## Довідник activation +## Довідка з activation -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane +Використовуйте `activation`, коли plugin може дешево оголосити, які події control plane мають включати його до плану активації/завантаження. Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє runtime-поведінку, не замінює `register(...)` і не гарантує, що -код Plugin уже виконано. Планувальник активації використовує ці поля, щоб -звузити список кандидатів Plugin перед fallback до наявних метаданих володіння -маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, +код plugin уже виконано. Планувальник активації використовує ці поля, щоб +звузити plugins-кандидати перед поверненням до наявних метаданих володіння в маніфесті, +як-от `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок -планувальнику, які не можна представити цими полями володіння. -Використовуйте top-level `cliBackends` для runtime-alias CLI, як-от `claude-cli`, -`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для -вбудованих ID agent harness, які ще не мають поля володіння. +планувальнику, які неможливо представити цими полями володіння. +Використовуйте верхньорівневий `cliBackends` для runtime-псевдонімів CLI, як-от `claude-cli`, +`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для +вбудованих ідентифікаторів agent harness, які ще не мають поля володіння. -Цей блок є лише метаданими. Він не реєструє runtime-поведінку і не -замінює `register(...)`, `setupEntry` чи інші runtime/plugin entrypoints. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не має -змінювати коректність, доки ще існують legacy fallback володіння маніфесту. +Цей блок є лише метаданими. Він не реєструє runtime-поведінку й не +замінює `register(...)`, `setupEntry` або інші runtime/plugin точки входу. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому +відсутні метадані активації не під час запуску зазвичай впливають лише на продуктивність; це +не має змінювати коректність, доки запасні варіанти володіння з маніфесту ще існують. -Кожен Plugin має свідомо встановлювати `activation.onStartup`, оскільки OpenClaw переходить -від неявних startup-імпортів. Установіть його в `true` лише тоді, коли Plugin повинен -виконуватися під час запуску Gateway. Установіть його в `false`, коли Plugin інертний під час -startup і має завантажуватися лише через вужчі тригери. Пропуск `onStartup` зберігає -застарілий legacy implicit startup sidecar fallback для Plugin без -статичних метаданих можливостей; майбутні версії можуть припинити startup-завантаження цих -Plugin, якщо вони не оголосять `activation.onStartup: true`. Звіти про статус і сумісність -Plugin попереджають із `legacy-implicit-startup-sidecar`, коли Plugin -досі покладається на цей fallback. - -Для тестування міграції встановіть -`OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1`, щоб вимкнути лише цей -застарілий fallback. Цей opt-in режим не блокує явні -Plugin з `activation.onStartup: true` або Plugin, завантажені каналом, конфігурацією, -agent-harness, пам’яттю чи іншими вужчими тригерами активації. +Кожен plugin має свідомо задавати `activation.onStartup`. Встановлюйте його в `true` +лише тоді, коли plugin має запускатися під час старту Gateway. Встановлюйте його в `false`, коли +plugin інертний під час запуску й має завантажуватися лише через вужчі тригери. +Пропуск `onStartup` більше не завантажує plugin під час запуску неявно; використовуйте явні +метадані активації для запуску, каналу, конфігурації, agent-harness, пам’яті або +інших вужчих тригерів активації. ```json { @@ -295,45 +286,45 @@ agent-harness, пам’яттю чи іншими вужчими тригера } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ----------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час запуску; `false` відмовляється від застарілого implicit sidecar startup fallback, якщо інший відповідний тригер не вимагає завантаження. | -| `onProviders` | Ні | `string[]` | ID постачальників, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Runtime ID вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте top-level `cliBackends` для alias backend CLI. | -| `onCommands` | Ні | `string[]` | ID команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | ID каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів startup/завантаження, коли шлях присутній і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовує планування активації control plane. Надавайте перевагу вужчим полям, коли це можливо. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен plugin має задавати це поле. `true` імпортує plugin під час запуску; `false` лишає його лінивим під час запуску, якщо інший відповідний тригер не потребує завантаження. | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Runtime-ідентифікатори вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Використовуйте верхньорівневий `cliBackends` для псевдонімів бекендів CLI. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки про можливості, які використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. | Поточні live-споживачі: -- Планування запуску Gateway використовує `activation.onStartup` для явного startup - імпорту та відмови від застарілого implicit sidecar startup fallback -- планування CLI, запущене командою, fallback до legacy +- Планування запуску Gateway використовує `activation.onStartup` для явного імпорту + під час запуску +- Планування CLI, ініційоване командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harness і top-level `cliBackends[]` для runtime-alias CLI -- планування setup/каналу, запущене каналом, fallback до legacy `channels[]` - володіння, коли явні метадані активації каналу відсутні -- планування Plugin під час startup використовує `activation.onConfigPaths` для неканальних root - поверхонь конфігурації, як-от блок `browser` вбудованого browser Plugin -- планування setup/runtime, запущене постачальником, fallback до legacy - `providers[]` і top-level `cliBackends[]` володіння, коли явні метадані активації постачальника - відсутні +- Планування запуску agent-runtime використовує `activation.onAgentHarnesses` для + вбудованих harness і верхньорівневий `cliBackends[]` для runtime-псевдонімів CLI +- Планування setup/channel, ініційоване каналом, повертається до застарілого + володіння `channels[]`, коли явні метадані активації каналу відсутні +- Планування plugin під час запуску використовує `activation.onConfigPaths` для неканальних кореневих + поверхонь конфігурації, як-от блок `browser` у bundled browser plugin +- Планування setup/runtime, ініційоване провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані + активації провайдера відсутні -Діагностика планувальника може відрізняти явні підказки активації від fallback -володіння маніфесту. Наприклад, `activation-command-hint` означає, що -`activation.onCommands` збігся, а `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці reason labels призначені для -діагностики хоста й тестів; автори Plugin мають і надалі оголошувати метадані, +Діагностика планувальника може відрізняти явні підказки активації від запасного варіанта +володіння з маніфесту. Наприклад, `activation-command-hint` означає, що +`activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що +планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для +діагностики хоста й тестів; автори plugin мають і далі оголошувати метадані, які найкраще описують володіння. -## Довідник qaRunners +## Довідка з qaRunners -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під -спільним коренем `openclaw qa`. Тримайте ці метадані дешевими й статичними; runtime -Plugin усе ще володіє фактичною реєстрацією CLI через легку +Використовуйте `qaRunners`, коли plugin додає один або кілька транспортних раннерів під +спільним коренем `openclaw qa`. Тримайте ці метадані дешевими й статичними; runtime plugin +усе ще володіє фактичною реєстрацією CLI через легковагу поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json @@ -347,15 +338,15 @@ Plugin усе ще володіє фактичною реєстрацією CLI } ``` -| Поле | Обов’язкове | Тип | Що означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------------ | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний довідковий текст, що використовується, коли спільному хосту потрібна команда-заглушка. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | -## довідник setup +## Довідка з setup -Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, що належать plugin, -перш ніж завантажиться runtime. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, +що належать plugin, перед завантаженням runtime. ```json { @@ -383,81 +374,53 @@ Plugin усе ще володіє фактичною реєстрацією CLI } ``` -Верхньорівневий `cliBackends` залишається чинним і далі описує бекенди CLI-виведення. -`setup.cliBackends` — це специфічна для setup поверхня дескрипторів для -потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається чинним і надалі описує бекенди CLI-інференсу. `setup.cliBackends` є специфічною для налаштування поверхнею дескрипторів для потоків площини керування/налаштування, які мають залишатися лише метаданими. -Коли `setup.providers` і `setup.cliBackends` наявні, вони є пріоритетною -поверхнею пошуку за дескрипторами для виявлення setup. Якщо дескриптор лише -звужує кандидатний plugin, а setup все ще потребує багатших runtime-хуків під час налаштування, -установіть `requiresRuntime: true` і залиште `setup-api` як -резервний шлях виконання. +Коли вони наявні, `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку за принципом «спочатку дескриптор» для виявлення налаштування. Якщо дескриптор лише звужує кандидатний plugin, а налаштування все ще потребує багатших runtime-хуків під час налаштування, задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальну автентифікацію provider і -пошуки env-var. `providerAuthEnvVars` лишається підтримуваним через адаптер сумісності -під час вікна застарівання, але небандловані plugins, які досі його використовують, -отримують діагностику manifest. Нові plugins мають розміщувати метадані env для setup/status -у `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` у загальний auth постачальника та пошук змінних середовища. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом вікна припинення підтримки, але незв’язані plugins, які досі його використовують, отримують діагностику маніфесту. Нові plugins мають розміщувати метадані змінних середовища для налаштування/статусу в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, -коли запис setup недоступний або коли `setup.requiresRuntime: false` -оголошує, що runtime для setup не потрібен. Явні записи `providerAuthChoices` лишаються -пріоритетними для кастомних міток, CLI-прапорців, області онбордингу та метаданих assistant. +OpenClaw також може виводити прості варіанти налаштування з `setup.providers[].authMethods`, коли запис налаштування недоступний або коли `setup.requiresRuntime: false` оголошує, що runtime налаштування не потрібен. Явні записи `providerAuthChoices` залишаються пріоритетними для користувацьких міток, прапорців CLI, області onboarding і метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескрипторах -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -plugin лише з дескрипторами все одно постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й продовжує її ігнорувати. Пропущений -`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали -дескриптори без цього прапорця, не зламалися. +Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні налаштування. OpenClaw трактує явне `false` як контракт лише на основі дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку налаштування. Якщо plugin, що працює лише на основі дескрипторів, усе ж постачає один із цих runtime-записів налаштування, OpenClaw повідомляє додаткову діагностику й надалі ігнорує його. Пропущений `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані -значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -виявлених plugins. Неоднозначне володіння завершується відмовою замість вибору -переможця за порядком виявлення. +Оскільки пошук налаштування може виконувати код `setup-api`, що належить plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених plugins. Неоднозначна належність завершується закритою відмовою замість вибору переможця за порядком виявлення. -Коли runtime setup таки виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, -якщо `setup-api` реєструє provider або CLI-бекенд, які не оголошені дескрипторами -manifest, або якщо дескриптор не має відповідної runtime-реєстрації. -Ця діагностика є додатковою й не відхиляє застарілі plugins. +Коли runtime налаштування виконується, діагностика реєстру налаштування повідомляє про розбіжність дескрипторів, якщо `setup-api` реєструє постачальника або бекенд CLI, якого не оголошують дескриптори маніфесту, або якщо дескриптор не має відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі plugins. -### довідник setup.providers +### Довідка setup.providers -| Поле | Обов’язкове | Тип | Що означає | -| -------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id provider, відкритий під час setup або онбордингу. Тримайте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | Id методів setup/auth, які цей provider підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. | -| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів auth для providers, що можуть автентифікуватися через несекретні маркери. | +| Поле | Обов’язково | Тип | Що це означає | +| -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ | +| `id` | Так | `string` | Ідентифікатор постачальника, доступний під час налаштування або onboarding. Тримайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/auth, які цей постачальник підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження runtime plugin. | +| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки auth-доказів для постачальників, які можуть автентифікуватися через несекретні маркери. | -`authEvidence` призначено для локальних маркерів облікових даних, що належать provider і можуть бути -перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: -без мережевих викликів, без читання keychain або secret-manager, без shell-команд і без -проб provider API. +`authEvidence` призначений для локальних маркерів облікових даних, що належать постачальнику та можуть бути перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або secret-manager, без shell-команд і без проб API постачальника. Підтримувані записи доказів: -| Поле | Обов’язкове | Тип | Що означає | -| ----------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------- | -| `type` | Так | `string` | Наразі `local-file-with-env`. | -| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файла облікових даних. | -| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, що перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | -| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна з перелічених env var має бути непорожньою, перш ніж доказ стане чинним. | -| `requiresAllEnv` | Ні | `string[]` | Кожна перелічена env var має бути непорожньою, перш ніж доказ стане чинним. | -| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | -| `source` | Ні | `string` | Користувацька мітка джерела для виводу auth/status. | +| Поле | Обов’язково | Тип | Що це означає | +| ------------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- | +| `type` | Так | `string` | Наразі `local-file-with-env`. | +| `fileEnvVar` | Ні | `string` | Змінна середовища, що містить явний шлях до файла облікових даних. | +| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, що перевіряються, коли `fileEnvVar` відсутній або порожній. Підтримує `${HOME}` і `${APPDATA}`. | +| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна наведена змінна середовища має бути непорожньою, перш ніж доказ буде чинним. | +| `requiresAllEnv` | Ні | `string[]` | Кожна наведена змінна середовища має бути непорожньою, перш ніж доказ буде чинним. | +| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | +| `source` | Ні | `string` | Видима користувачу мітка джерела для виводу auth/статусу. | -### поля setup +### Поля setup -| Поле | Обов’язкове | Тип | Що означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------ | -| `providers` | Ні | `object[]` | Дескриптори setup provider, відкриті під час setup і онбордингу. | -| `cliBackends` | Ні | `string[]` | Id бекендів часу setup, що використовуються для пошуку setup спершу за дескрипторами. Тримайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, що належать поверхні setup цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку за дескрипторами. | +| Поле | Обов’язково | Тип | Що це означає | +| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори налаштування постачальника, доступні під час налаштування та onboarding. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів під час налаштування, що використовуються для пошуку налаштування за принципом «спочатку дескриптор». Тримайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні налаштування цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи налаштування все ще потребує виконання `setup-api` після пошуку за дескриптором. | -## довідник uiHints +## Довідка uiHints `uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. @@ -476,19 +439,18 @@ manifest, або якщо дескриптор не має відповідно Кожна підказка поля може містити: -| Поле | Тип | Що означає | -| ------------- | ---------- | ------------------------------------------- | -| `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` | Текст placeholder для полів форми. | -## довідник contracts +## Довідка contracts -Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може -читати без імпорту runtime plugin. +Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може читати без імпорту runtime plugin. ```json { @@ -510,49 +472,34 @@ manifest, або якщо дескриптор не має відповідно } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: -| Поле | Тип | Що означає | -| -------------------------------- | ---------- | -------------------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Id фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Runtime id, для яких бандлований plugin може зареєструвати middleware результатів tool. | -| `externalAuthProviders` | `string[]` | Id provider, чий хук зовнішнього профілю auth належить цьому plugin. | -| `speechProviders` | `string[]` | Id speech provider, що належать цьому plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id realtime-transcription provider, що належать цьому plugin. | -| `realtimeVoiceProviders` | `string[]` | Id realtime-voice provider, що належать цьому plugin. | -| `memoryEmbeddingProviders` | `string[]` | Id memory embedding provider, що належать цьому plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id media-understanding provider, що належать цьому plugin. | -| `imageGenerationProviders` | `string[]` | Id image-generation provider, що належать цьому plugin. | -| `videoGenerationProviders` | `string[]` | Id video-generation provider, що належать цьому plugin. | -| `webFetchProviders` | `string[]` | Id web-fetch provider, що належать цьому plugin. | -| `webSearchProviders` | `string[]` | Id web-search provider, що належать цьому plugin. | -| `migrationProviders` | `string[]` | Id import provider, що належать цьому plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви agent tools, що належать цьому plugin для бандлованих перевірок контрактів. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | --------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Runtime-ідентифікатори, для яких вбудований plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори постачальників, чий хук зовнішнього auth-профілю належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори постачальників мовлення, що належать цьому plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори постачальників realtime-транскрипції, що належать цьому plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори постачальників realtime-голосу, що належать цьому plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори постачальників memory embedding, що належать цьому plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори постачальників media-understanding, що належать цьому plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори постачальників генерації зображень, що належать цьому plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори постачальників генерації відео, що належать цьому plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори постачальників web-fetch, що належать цьому plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори постачальників web-search, що належать цьому plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори постачальників імпорту, що належать цьому plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, що належать цьому plugin для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для бандлованих фабрик розширень Codex, -призначених лише для app-server. Бандловані перетворення результатів tool мають -оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть -реєструвати middleware результатів tool, оскільки цей seam може переписувати вивід tool -із високим рівнем довіри до того, як його побачить модель. +`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик розширень, призначених лише для app-server Codex. Вбудовані перетворення результатів інструментів мають натомість оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть реєструвати middleware результатів інструментів, бо ця поверхня може переписувати високодовірений вивід інструментів до того, як модель його побачить. -Provider plugins, що реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugins без цього оголошення все одно проходять -через застарілий резервний шлях сумісності, але він повільніший і -буде вилучений після вікна міграції. +Plugins постачальників, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugins без такого оголошення все ще виконуються через застарілий резервний шлях сумісності, але цей резервний шлях повільніший і буде вилучений після вікна міграції. -Бандловані providers memory embedding мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони відкривають, зокрема -вбудованих адаптерів на кшталт `local`. Самостійні CLI-шляхи використовують цей manifest -contract, щоб завантажити лише власний plugin до того, як повний runtime Gateway -зареєструє providers. +Вбудовані постачальники memory embedding мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажити лише plugin-власника до того, як повний runtime Gateway зареєструє постачальників. -## довідник mediaUnderstandingProviderMetadata +## Довідка mediaUnderstandingProviderMetadata -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має -типові моделі, пріоритет резервної автоавтентифікації або вбудовану підтримку документів, -які потрібні загальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в -`contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли постачальник media-understanding має моделі за замовчуванням, пріоритет fallback для auto-auth або нативну підтримку документів, які потрібні загальним core-хелперам до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -575,26 +522,26 @@ contract, щоб завантажити лише власний plugin до то } ``` -Кожен запис провайдера може містити: +Кожен запис постачальника може містити: -| Поле | Тип | Що це означає | -| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові зіставлення можливостей із моделями, що використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані вхідні документи, які підтримує провайдер. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей постачальник. | +| `defaultModels` | `Record` | Типові відповідності можливостей до моделей, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору постачальника на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує постачальник. | -## Довідник `channelConfigs` +## довідка channelConfigs Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження середовища виконання. Виявлення налаштування/стану каналу в режимі лише для читання може використовувати ці метадані +завантаження runtime. Доступне лише для читання виявлення налаштування/стану каналу може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний, або -коли `setup.requiresRuntime: false` оголошує, що середовище виконання для налаштування непотрібне. +коли `setup.requiresRuntime: false` оголошує runtime налаштування непотрібним. `channelConfigs` — це метадані маніфесту Plugin, а не новий розділ користувацької конфігурації верхнього рівня. Користувачі й надалі налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим -каналом, до виконання коду середовища виконання Plugin. +OpenClaw читає метадані маніфесту, щоб визначити, якому Plugin належить цей налаштований +канал до виконання runtime-коду Plugin. Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: @@ -604,14 +551,14 @@ OpenClaw читає метадані маніфесту, щоб визначит Невбудовані plugins, які оголошують `channels[]`, також мають оголошувати відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але -схема конфігурації, налаштування й поверхні інтерфейсу керування на холодному шляху не зможуть знати -форму параметрів, що належать каналу, доки не виконається середовище виконання Plugin. +схема конфігурації холодного шляху, налаштування та поверхні Control UI не зможуть знати +форму параметрів, що належать каналу, доки не виконається runtime Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і `nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, -які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати -такі самі типові значення через `package.json#openclaw.channel.commands` разом -з іншими метаданими каталогу каналів, що належать пакету. +які виконуються до завантаження runtime каналу. Вбудовані канали також можуть публікувати +ті самі типові значення через `package.json#openclaw.channel.commands` разом з +іншими метаданими каталогу каналів, що належать пакету. ```json { @@ -644,19 +591,19 @@ OpenClaw читає метадані маніфесту, щоб визначит Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------ | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові підказки для міток/заповнювачів/чутливих даних інтерфейсу для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору й інспектування, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспектування й каталогу. | -| `commands` | `object` | Статичні автоматичні типові значення вбудованих команд і вбудованих Skills для перевірок конфігурації до середовища виконання. | -| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори plugins, які цей канал має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові UI мітки/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору й інспектування, коли runtime-метадані ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспектування й каталогу. | +| `commands` | `object` | Статичні автоматичні типові значення нативних команд і нативних Skills для перевірок конфігурації до runtime. | +| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори plugins, які цей канал має випереджати в поверхнях вибору. | ### Заміна іншого Plugin каналу Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який -може також надавати інший Plugin. Типові випадки — перейменований ідентифікатор Plugin, +може також надавати інший Plugin. Поширені випадки — перейменований ідентифікатор Plugin, окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який зберігає той самий ідентифікатор каналу для сумісності конфігурації. @@ -679,21 +626,21 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та +Коли `channels.chat` налаштовано, OpenClaw враховує і ідентифікатор каналу, і ідентифікатор бажаного Plugin. Якщо нижчопріоритетний Plugin було вибрано лише тому, що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній -конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача -все одно має перевагу: якщо користувач явно вмикає обидва plugins, OpenClaw +runtime-конфігурації, щоб каналом і його інструментами володів один Plugin. Явний +вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва plugins, OpenClaw зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість тихої зміни запитаного набору plugins. -Обмежуйте `preferOver` лише ідентифікаторами plugins, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. +Обмежуйте `preferOver` ідентифікаторами plugins, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету й воно не перейменовує ключі користувацької конфігурації. -## Довідник `modelSupport` +## довідка modelSupport -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з -скорочених ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin постачальника з +коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime Plugin. ```json @@ -705,27 +652,28 @@ Plugin. } ``` -OpenClaw застосовує такий порядок пріоритетів: +OpenClaw застосовує такий пріоритет: - явні посилання `provider/model` використовують метадані маніфесту `providers` власника - `modelPatterns` мають перевагу над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований +- якщо один невбудований Plugin і один вбудований Plugin збігаються, перемагає невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не задасть провайдера +- решта неоднозначностей ігнорується, доки користувач або конфігурація не задасть постачальника Поля: | Поле | Тип | Що це означає | | --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела регулярних виразів, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` із короткими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються з короткими ідентифікаторами моделей після вилучення суфікса профілю. | -## Довідник `modelCatalog` +## довідка modelCatalog -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження середовища виконання Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, -псевдонімів провайдерів, правил пригнічення та режиму виявлення. Оновлення середовища виконання -й надалі належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли потрібне середовище виконання. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей постачальника до +завантаження runtime Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, +псевдонімів постачальника, правил придушення та режиму виявлення. Runtime-оновлення +й надалі належить runtime-коду постачальника, але маніфест повідомляє core, коли runtime +є обов’язковим. ```json { @@ -776,71 +724,71 @@ OpenClaw застосовує такий порядок пріоритетів: Поля верхнього рівня: -| Поле | Тип | Що це означає | -| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, що належать цьому Plugin. Ключі також мають з’являтися в `providers` верхнього рівня. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися до власного провайдера для планування каталогу або пригнічення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin пригнічує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати його в кеш або чи потрібне середовище виконання. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів постачальників, що належать цьому Plugin. Ключі також мають бути в `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми постачальників, які мають зіставлятися з власним постачальником для планування каталогу або придушень. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin придушує з причини, специфічної для постачальника. | +| `discovery` | `Record` | Чи можна каталог постачальника читати з метаданих маніфесту, оновлювати в кеші, чи він потребує runtime. | -`aliases` бере участь у пошуку власника провайдера для планування каталогу моделей. -Цілі псевдонімів мають бути провайдерами верхнього рівня, що належать тому самому Plugin. Коли -список, відфільтрований за провайдером, використовує псевдонім, OpenClaw може читати маніфест власника та -застосовувати перевизначення API/базової URL-адреси псевдоніма без завантаження середовища виконання провайдера. -Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки -канонічного провайдера-власника. +`aliases` бере участь у пошуку власника постачальника для планування model-catalog. +Цілі псевдонімів мають бути постачальниками верхнього рівня, що належать тому самому Plugin. Коли +список, відфільтрований за постачальником, використовує псевдонім, OpenClaw може прочитати маніфест власника та +застосувати перевизначення API/base URL псевдоніма без завантаження runtime постачальника. +Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише +рядки канонічного постачальника-власника. -`suppressions` замінює старий хук середовища виконання провайдера `suppressBuiltInModel`. -Записи пригнічення враховуються лише тоді, коли провайдер належить Plugin або -оголошений як ключ `modelCatalog.aliases`, що вказує на власного провайдера. Хуки пригнічення -середовища виконання більше не викликаються під час розв’язання моделей. +`suppressions` замінює старий runtime-хук постачальника `suppressBuiltInModel`. +Записи придушення враховуються лише тоді, коли постачальник належить Plugin або +оголошений як ключ `modelCatalog.aliases`, що вказує на власного постачальника. Runtime- +хуки придушення більше не викликаються під час розв’язання моделі. -Поля провайдера: +Поля постачальника: -| Поле | Тип | Що це означає | -| --------- | ------------------------ | -------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язкова типова базова URL-адреса для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що це означає | +| --------- | ------------------------ | ----------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язкова типова базова URL-адреса для моделей у цьому каталозі постачальника. | +| `api` | `ModelApi` | Необов’язковий типовий API-адаптер для моделей у цьому каталозі постачальника. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу постачальника. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що це означає | -| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі, без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення базової URL-адреси для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку міркування. | -| `contextWindow` | `number` | Нативне контекстне вікно провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, коли воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язкове `tieredPricing`. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова назва для відображення. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення базової URL-адреси для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які модель приймає. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Нативне вікно контексту провайдера. | +| `contextTokens` | `number` | Необов’язкова ефективна межа контексту під час виконання, якщо вона відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| `cost` | `object` | Необов’язкова ціна в доларах США за мільйон токенів, включно з необов’язковим `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок узагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від доступного. | -| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору та фільтри. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Пригнічуйте лише тоді, коли рядок узагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від available. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-замінника для deprecated-рядків. | +| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | -Поля приховування: +Поля пригнічення: -| Поле | Тип | Що це означає | -| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно приховати. Має належати цьому plugin або бути оголошеним як належний псевдонім. | -| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно приховати. | -| `reason` | `string` | Необов’язкове повідомлення, що показується, коли прихований рядок запитують напряму. | -| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базових URL провайдера, потрібних перед застосуванням приховування. | -| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` з конфігурації провайдера, потрібних перед застосуванням приховування. | +| Поле | Тип | Що це означає | +| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно пригнітити. Має належати цьому plugin або бути оголошеним як власний псевдонім. | +| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно пригнітити. | +| `reason` | `string` | Необов’язкове повідомлення, що показується, коли пригнічений рядок запитують напряму. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базових URL провайдера, потрібних для застосування пригнічення. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` у конфігурації провайдера, потрібних для застосування пригнічення. | -Не розміщуйте дані лише часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку з фільтрацією за провайдером і засоби вибору могли пропустити виявлення через реєстр або runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення чи кеш можуть додати більше рядків пізніше; рядки `refreshable` самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб знати список. +Не розміщуйте дані лише для часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списків і вибору з фільтрацією за провайдером могли пропускати виявлення registry/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як перелічувані початкові дані або доповнення, але refresh/cache може згодом додати більше рядків; refreshable-рядки самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб дізнатися список. -## Довідка modelIdNormalization +## Довідник modelIdNormalization -Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, що належить провайдеру й має відбутися до завантаження runtime провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті власного plugin, а не в основних таблицях вибору моделей. +Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, що належить провайдеру й має виконуватися до завантаження runtime провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера legacy-ідентифікатори та правила префіксів proxy, у маніфесті власного plugin, а не в основних таблицях вибору моделей. ```json { @@ -862,31 +810,31 @@ OpenClaw застосовує такий порядок пріоритетів: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------- | -| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | -| `stripPrefixes` | `string[]` | Префікси, які потрібно видалити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксації bare-id після пошуку псевдоніма, ключовані за `modelPrefix` і `prefix`. | +| Поле | Тип | Що це означає | +| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | +| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються так, як записані. | +| `stripPrefixes` | `string[]` | Префікси, які потрібно видалити перед пошуком псевдоніма; корисно для legacy-дублювання provider/model. | +| `prefixWhenBare` | `string` | Префікс, який додається, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса bare-ідентифікатора після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | -## Довідка providerEndpoints +## Довідник providerEndpoints -Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Core і далі володіє значенням кожного `endpointClass`; маніфести plugin володіють метаданими хоста й базової URL-адреси. +Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Core і далі визначає значення кожного `endpointClass`; маніфести plugin володіють метаданими хоста й базової URL-адреси. Поля endpoint: -| Поле | Тип | Що це означає | -| ----------------------------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | Відомий core-клас endpoint, як-от `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, що відповідають класу endpoint. | -| `hostSuffixes` | `string[]` | Суфікси хостів, що відповідають класу endpoint. Додавайте префікс `.` для зіставлення лише суфікса домену. | -| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, що відповідають класу endpoint. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | +| Поле | Тип | Що це означає | +| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | Відомий core-клас endpoint, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | +| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом endpoint. | +| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом endpoint. Додавайте префікс `.` для зіставлення лише із суфіксом домену. | +| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, які зіставляються з класом endpoint. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно видалити зі збіжних хостів, щоб відкрити префікс регіону Google Vertex. | -## Довідка providerRequest +## Довідник providerRequest -Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Тримайте переписування payload, специфічне для поведінки, у runtime-хуках провайдера або спільних допоміжних функціях сімейства провайдерів. +Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Тримайте специфічне для поведінки переписування payload у runtime-хуках провайдера або спільних helper для сімейств провайдерів. ```json { @@ -906,15 +854,15 @@ OpenClaw застосовує такий порядок пріоритетів: Поля провайдера: -| Поле | Тип | Що це означає | -| --------------------- | ------------ | ---------------------------------------------------------------------------------------------- | -| `family` | `string` | Мітка сімейства провайдерів, яку використовують загальні рішення щодо сумісності запитів і діагностика. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства провайдерів для спільних допоміжних функцій запитів. | -| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | +| Поле | Тип | Що це означає | +| --------------------- | ------------ | -------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства провайдера, що використовується загальними рішеннями сумісності запитів і діагностикою. | +| `compatibilityFamily` | `"moonshot"` | Необов’язковий compatibility bucket сімейства провайдера для спільних helper запитів. | +| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | -## Довідка modelPricing +## Довідник modelPricing -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш ціноутворення Gateway читає ці метадані без імпорту коду runtime провайдера. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка pricing у control plane до завантаження runtime. Кеш pricing у Gateway читає ці метадані без імпорту runtime-коду провайдера. ```json { @@ -937,133 +885,133 @@ OpenClaw застосовує такий порядок пріоритетів: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------ | -| `external` | `boolean` | Установіть `false` для локальних або self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Відображення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Відображення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| Поле | Тип | Що це означає | +| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не повинні отримувати ціни OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що це означає | -| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------ | -| `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей із скісною рискою як вкладені посилання provider/model, корисно для проксі-провайдерів, таких як OpenRouter. | +| Поле | Тип | Що це означає | +| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор зовнішнього провайдера каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | +| `passthroughProviderModel` | `boolean` | Обробляти ідентифікатори моделей зі скісною рискою як вкладені refs provider/model; корисно для proxy-провайдерів, як-от OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом щодо встановлених plugin. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні installable-provider і засобів вибору моделей до встановлення використовуватимуть, коли plugin провайдера не встановлено. +Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для встановлених plugin. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні встановлюваних провайдерів і pre-install засобів вибору моделей споживатимуть, коли plugin провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. 2. `modelCatalog` маніфесту встановленого plugin. -3. Кеш каталогу моделей після явного оновлення. +3. Кеш каталогу моделей з явного refresh. 4. Preview-рядки Індексу провайдерів OpenClaw. Індекс провайдерів не повинен містити секрети, увімкнений стан, runtime-хуки або -живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести плагінів, але мають залишатися обмеженими -стабільними метаданими відображення, якщо поля runtime-адаптера, як-от `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з -маніфестом установленого плагіна. Провайдери з live-виявленням `/models` мають -записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, -щоб звичайний список або onboarding викликав API провайдера. +живі дані моделей, специфічні для облікового запису. Його попередні каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими +стабільними відображуваними метаданими, якщо runtime-поля адаптера, як-от `api`, +`baseUrl`, ціни або прапорці сумісності, навмисно не підтримуються узгодженими з +маніфестом установленого Plugin. Провайдери з живим виявленням `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей, а не +змушувати звичайний список або onboarding викликати API провайдера. -Записи Індексу провайдерів також можуть містити метадані installable-plugin для провайдерів, -чий плагін було винесено з core або інакше ще не встановлено. Ці -метадані віддзеркалюють патерн каталогу каналів: назви пакета, npm install spec, +Записи Індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, +чий Plugin було винесено з core або який інакше ще не встановлено. Ці +метадані віддзеркалюють шаблон каталогу каналів: назви пакета, специфікації npm install, очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати -інсталюваний варіант налаштування. Після встановлення плагіна його маніфест має пріоритет, а +встановлюваний варіант налаштування. Коли Plugin встановлено, перемагає його маніфест, а запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі capability-ключі верхнього рівня deprecated. Використовуйте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня вважаються deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння -capability. +можливостями. -## Manifest проти package.json +## Маніфест порівняно з package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація config, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду плагіна | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint-ів, install gating, setup або метаданих каталогу | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані вибору автентифікації та UI-підказки, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, install gating, налаштування або метаданих каталогу | -Якщо ви не впевнені, де має бути певна частина метаданих, скористайтеся цим правилом: +Якщо ви не впевнені, де має бути певна частина метаданих, використовуйте це правило: -- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, entry-файлів або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів входу або поведінки npm install, помістіть це в `package.json` -### Поля package.json, які впливають на виявлення +### Поля package.json, що впливають на виявлення -Деякі pre-runtime метадані плагіна навмисно живуть у `package.json` під -блоком `openclaw` замість `openclaw.plugin.json`. +Деякі pre-runtime метадані Plugin навмисно зберігаються в `package.json` під +блоком `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує native entrypoint-и плагіна. Має залишатися всередині каталогу пакета плагіна. | -| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoint-и для встановлених пакетів. Має залишатися всередині каталогу пакета плагіна. | -| `openclaw.setupEntry` | Легкий setup-only entrypoint, що використовується під час onboarding, відкладеного запуску каналу та read-only status/SecretRef discovery каналу. Має залишатися всередині каталогу пакета плагіна. | -| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript setup entrypoint для встановлених пакетів. Потребує `setupEntry`, має існувати й залишатися всередині каталогу пакета плагіна. | -| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст вибору. | -| `openclaw.channel.commands` | Статичні native command і native skill auto-default метадані, що використовуються config, audit і command-list поверхнями до завантаження runtime каналу. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти «чи вже існує env-only setup?» без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти «чи хтось уже ввійшов?» без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки install/update для вбудованих і зовнішньо опублікованих плагінів. | +| `openclaw.extensions` | Оголошує нативні entrypoints Plugin. Має залишатися всередині директорії пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoints для встановлених пакетів. Має залишатися всередині директорії пакета Plugin. | +| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час onboarding, відкладеного запуску каналу та read-only статусу каналу/виявлення SecretRef. Має залишатися всередині директорії пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript setup entrypoint для встановлених пакетів. Потребує `setupEntry`, має існувати та має залишатися всередині директорії пакета Plugin. | +| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст вибору. | +| `openclaw.channel.commands` | Статичні метадані нативних команд і auto-default нативних skill, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легкі метадані перевіряча configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевіряча persisted-auth, які можуть відповісти на запитання «чи вже є щось авторизоване?» без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення для bundled і зовнішньо опублікованих Plugins. | | `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, з використанням semver floor на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок npm dist integrity, як-от `sha512-...`; потоки install і update перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення reinstall для вбудованого плагіна, коли config недійсний. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє setup-only поверхням каналу завантажуватися перед повним плагіном каналу під час startup. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, з використанням semver-порога на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях recovery через перевстановлення bundled Plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналу лише для налаштування завантажуватися до повного Plugin каналу під час startup. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє -onboarding, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих -варіантів. Не переносіть install-підказки в `openclaw.plugin.json`. +onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих +варіантів. Не переміщуйте підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час install і завантаження -registry маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають -плагін на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження +реєстру маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають +Plugin на старіших хостах. -Точне pinning npm-версії вже живе в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні external catalog -entries мають поєднувати exact specs з `expectedIntegrity`, щоб update flows fail -closed, якщо отриманий npm artifact більше не відповідає pinned release. -Інтерактивний onboarding досі пропонує trusted registry npm specs, включно з bare -package names і dist-tags, для сумісності. Діагностика каталогу може -розрізняти exact, floating, integrity-pinned, missing-integrity, package-name -mismatch і invalid default-choice sources. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає дійсного npm source, який він може pin. +Точне фіксування версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення fail closed, +якщо отриманий npm-артефакт більше не відповідає зафіксованому релізу. +Інтерактивний onboarding усе ще пропонує довірені специфікації npm із registry, зокрема bare +назви пакетів і dist-tags, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, integrity-pinned джерела, missing-integrity, package-name +mismatch і invalid default-choice джерела. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає дійсного npm-джерела, яке він може зафіксувати. Коли `expectedIntegrity` присутній, -install/update flows enforce it; коли його omitted, registry resolution +потоки встановлення/оновлення застосовують його; коли його опущено, registry resolution записується без integrity pin. -Плагіни каналів мають надавати `openclaw.setupEntry`, коли status, channel list -або SecretRef scans мають визначити configured accounts без завантаження повного -runtime. Setup entry має expose метадані каналу плюс setup-safe config, -status і secrets adapters; тримайте network clients, gateway listeners і -transport runtimes в основному entrypoint розширення. +Channel Plugins мають надавати `openclaw.setupEntry`, коли статус, список каналів +або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного +runtime. Setup entry має експортувати метадані каналу плюс setup-safe адаптери конфігурації, +статусу та секретів; залишайте мережеві клієнти, gateway listeners і +transport runtimes в основному entrypoint extension. Поля runtime entrypoint не перевизначають перевірки меж пакета для source entrypoint fields. Наприклад, `openclaw.runtimeExtensions` не може зробити -escaping path `openclaw.extensions` придатним до завантаження. +escaping шлях `openclaw.extensions` придатним до завантаження. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не -робить довільні зламані configs installable. Сьогодні він лише дозволяє install -flows відновлюватися після конкретних stale bundled-plugin upgrade failures, таких як -відсутній шлях bundled plugin або stale запис `channels.` для того самого -bundled plugin. Непов’язані config errors досі block install і спрямовують операторів +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить +довільні зламані конфігурації встановлюваними. Сьогодні він лише дозволяє install +flows відновлюватися після конкретних застарілих помилок оновлення bundled Plugin, як-от +відсутній шлях bundled Plugin або застарілий запис `channels.` для того самого +bundled Plugin. Непов’язані помилки конфігурації все ще блокують install і спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` є метаданими пакета для крихітного checker +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного checker module: ```json @@ -1080,12 +1028,12 @@ module: } ``` -Використовуйте це, коли setup, doctor, status або read-only presence flows потребують cheap -yes/no auth probe до завантаження повного плагіна каналу. Persisted auth state не є -configured channel state: не використовуйте ці метадані, щоб auto-enable plugins, -repair runtime dependencies або вирішувати, чи має завантажуватися runtime каналу. -Цільовий export має бути невеликою function, яка читає лише persisted state; не -маршрутизуйте його через повний runtime barrel каналу. +Використовуйте це, коли setup, doctor, status або read-only presence flows потребують дешевого +yes/no auth probe до завантаження повного Plugin каналу. Persisted auth state — це +не configured channel state: не використовуйте ці метадані для auto-enable Plugins, +repair runtime dependencies або рішення, чи має завантажуватися runtime каналу. +Цільовий export має бути невеликою функцією, яка читає лише persisted state; не +проводьте його через повний runtime barrel каналу. `openclaw.channel.configuredState` має таку саму форму для дешевих env-only configured checks: @@ -1104,58 +1052,58 @@ configured checks: } ``` -Використовуйте це, коли канал може відповісти про configured-state з env або інших tiny -non-runtime inputs. Якщо перевірка потребує full config resolution або реального -runtime каналу, тримайте цю логіку в hook плагіна `config.hasConfiguredState` -замість цього. +Використовуйте це, коли канал може відповісти щодо configured-state з env або інших крихітних +non-runtime inputs. Якщо перевірка потребує повного config resolution або реального +runtime каналу, залишайте цю логіку в hook `config.hasConfiguredState` +Plugin. -## Пріоритет виявлення (дубльовані id плагінів) +## Пріоритетність виявлення (дублікати id Plugin) -OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, workspace, явні config-selected paths). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє Plugins із кількох roots (bundled, global install, workspace, explicit config-selected paths). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищою пріоритетністю**; дублікати з нижчою пріоритетністю відкидаються замість завантаження поруч із ним. -Пріоритет від найвищого до найнижчого: +Пріоритетність, від найвищої до найнижчої: -1. **Config-selected** — шлях, явно pinned у `plugins.entries.` -2. **Bundled** — плагіни, що постачаються з OpenClaw -3. **Global install** — плагіни, встановлені в глобальний корінь плагінів OpenClaw -4. **Workspace** — плагіни, виявлені відносно поточного workspace +1. **Config-selected** — шлях, явно зафіксований у `plugins.entries.` +2. **Bundled** — Plugins, що постачаються з OpenClaw +3. **Global install** — Plugins, установлені в global OpenClaw plugin root +4. **Workspace** — Plugins, виявлені відносно поточного workspace Наслідки: -- Forked або stale копія bundled plugin, що лежить у workspace, не затінить bundled build. -- Щоб справді перевизначити bundled plugin локальним, pin його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладався на workspace discovery. +- Forked або застаріла копія bundled Plugin, що лежить у workspace, не затінить bundled build. +- Щоб справді перевизначити bundled Plugin локальним, зафіксуйте його через `plugins.entries.`, щоб він переміг за пріоритетністю, а не покладайтеся на workspace discovery. - Відкидання дублікатів логуються, щоб Doctor і startup diagnostics могли вказати на відкинуту копію. ## Вимоги JSON Schema -- **Кожен плагін має постачати JSON Schema**, навіть якщо він не приймає config. +- **Кожен Plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. - Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Schemas валідуються під час config read/write, а не в runtime. +- Schemas перевіряються під час читання/запису конфігурації, а не під час runtime. -## Поведінка валідації +## Поведінка перевірки -- Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено маніфестом Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено в маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. -- Якщо Plugin встановлено, але його маніфест або схема пошкоджені чи відсутні, - перевірка завершується невдало, а Doctor повідомляє про помилку Plugin. +- Якщо Plugin встановлено, але він має пошкоджений або відсутній маніфест чи схему, + перевірка не проходить, а Doctor повідомляє про помилку Plugin. - Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, а **попередження** відображається в Doctor + журналах. -Повну схему `plugins.*` див. у [довіднику з конфігурації](/uk/gateway/configuration). +Див. [довідник конфігурації](/uk/gateway/configuration), щоб переглянути повну схему `plugins.*`. ## Примітки -- Маніфест є **обов’язковим для нативних Plugin OpenClaw**, зокрема для завантажень із локальної файлової системи. Runtime все одно завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення та перевірки. -- Нативні маніфести аналізуються за допомогою JSON5, тому коментарі, завершальні коми й ключі без лапок приймаються, якщо кінцеве значення все ще є об’єктом. +- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання все одно завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення + перевірки. +- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок приймаються, доки кінцеве значення все ще є об’єктом. - Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо Plugin вони не потрібні. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні види Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). -- Оголошуйте ексклюзивний вид Plugin у цьому маніфесті. Runtime-запис `OpenClawPluginDefinition.kind` застарів і залишається лише як резервна сумісність для старіших Plugin. -- Метадані змінних середовища (`setup.providers[].envVars`, застарілі `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для runtime-метаданих майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin вони не потрібні. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати великий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Оголошуйте ексклюзивний тип Plugin у цьому маніфесті. `OpenClawPluginDefinition.kind` у точці входу середовища виконання застарів і залишається лише як резерв сумісності для старіших Plugin. +- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставки cron та інші поверхні лише для читання все одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Для метаданих майстра середовища виконання, які потребують коду провайдера, див. [хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до списку дозволів менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане @@ -1167,6 +1115,6 @@ OpenClaw виявляє плагіни з кількох коренів (вбу Внутрішня архітектура та модель можливостей. - Довідник Plugin SDK та імпорти підшляхів. + Довідник SDK Plugin та імпорти підшляхів. diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 1dc62f5cc..03edb525c 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,102 +1,84 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Вам потрібна автентифікація через підписку Codex замість ключів API + - Вам потрібна автентифікація через передплату Codex замість API-ключів - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використовуйте OpenAI через ключі API або підписку Codex в OpenClaw +summary: Використовуйте OpenAI через ключі API або передплату Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-30T13:51:27Z" + generated_at: "2026-05-01T22:03:36Z" model: gpt-5.5 provider: openai - source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad + source_hash: bd9a8f05d31800354307c6fd7beb8cd1eed3d234e5c1e939e895cd99658b540b source_path: providers/openai.md workflow: 16 --- -OpenAI надає API для розробників для моделей GPT, а Codex також доступний як -агент для програмування в межах плану ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці -поверхні окремо, щоб конфігурація залишалася передбачуваною. +OpenAI надає developer API для моделей GPT, а Codex також доступний як агент для програмування в плані ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці поверхні окремо, щоб конфігурація залишалася передбачуваною. -OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі вибирає -маршрут провайдера/автентифікації; окреме налаштування середовища виконання вибирає, хто виконує -вбудований цикл агента: +OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі вибирає маршрут провайдера/автентифікації; окреме налаштування runtime вибирає, хто виконує вбудований цикл агента: - **Ключ API** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) -- **Підписка Codex через PI** — вхід ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`) -- **Оснастка app-server Codex** — нативне виконання app-server Codex (моделі `openai/*` плюс `agents.defaults.agentRuntime.id: "codex"`) +- **Підписка Codex через PI** — вхід ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`) +- **Обв’язка Codex app-server** — нативне виконання Codex app-server (моделі `openai/*` плюс `agents.defaults.agentRuntime.id: "codex"`) -OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI явно підтримує використання OAuth за підпискою в зовнішніх інструментах і робочих процесах на кшталт OpenClaw. -Провайдер, модель, середовище виконання та канал — це окремі рівні. Якщо ці мітки -змішуються між собою, прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes), перш ніж -змінювати конфігурацію. +Провайдер, модель, runtime і канал — це окремі шари. Якщо ці мітки змішуються між собою, прочитайте [runtime агентів](/uk/concepts/agent-runtimes), перш ніж змінювати конфігурацію. ## Швидкий вибір -| Мета | Використовуйте | Примітки | +| Ціль | Використовуйте | Примітки | | --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | -| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть онбординг ключа API OpenAI. | -| GPT-5.5 з автентифікацією підписки ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для OAuth Codex. Найкращий перший вибір для налаштувань із підпискою. | -| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово вмикає оснастку app-server Codex для цього посилання на модель. | -| Генерація або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OpenAI Codex OAuth. | +| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть onboarding ключа API OpenAI. | +| GPT-5.5 з автентифікацією підписки ChatGPT/Codex | `openai-codex/gpt-5.5` | Стандартний маршрут PI для OAuth Codex. Найкращий перший вибір для налаштувань із підпискою. | +| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово вмикає обв’язку Codex app-server для цього посилання на модель. | +| Генерація або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OAuth OpenAI Codex. | | Зображення з прозорим фоном | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | -## Карта назв +## Мапа назв -Назви подібні, але не взаємозамінні: +Назви схожі, але не взаємозамінні: -| Назва, яку ви бачите | Рівень | Значення | +| Назва, яку ви бачите | Шар | Значення | | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | -| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. | -| `openai-codex` | Префікс провайдера | Маршрут OAuth/підписки OpenAI Codex через звичайний runner PI OpenClaw. | -| `codex` plugin | Plugin | Вбудований Plugin OpenClaw, який надає нативне середовище виконання app-server Codex і елементи керування чатом `/codex`. | -| `agentRuntime.id: codex` | Середовище виконання агента | Примусово вмикає нативну оснастку app-server Codex для вбудованих ходів. | -| `/codex ...` | Набір команд чату | Прив’язуйте/керуйте потоками app-server Codex із розмови. | -| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний резервний шлях, який запускає Codex через ACP/acpx. | +| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. | +| `openai-codex` | Префікс провайдера | Маршрут OAuth/підписки OpenAI Codex через звичайний runner OpenClaw PI. | +| Plugin `codex` | Plugin | Вбудований Plugin OpenClaw, який надає нативний runtime Codex app-server і керування чатом `/codex`. | +| `agentRuntime.id: codex` | Runtime агента | Примусово використовує нативну обв’язку Codex app-server для вбудованих ходів. | +| `/codex ...` | Набір команд чату | Прив’язує/керує потоками Codex app-server з розмови. | +| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний fallback-шлях, який запускає Codex через ACP/acpx. | -Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і -Plugin `codex`. Це коректно, коли вам потрібен OAuth Codex через PI, а також потрібно, -щоб були доступні нативні елементи керування чатом `/codex`. `openclaw doctor` попереджає про цю -комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її. +Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і Plugin `codex`. Це коректно, коли потрібен OAuth Codex через PI, а також доступне нативне керування чатом `/codex`. `openclaw doctor` попереджає про таку комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її. -GPT-5.5 доступна як через прямий доступ за ключем API OpenAI Platform, так і через -маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку -`OPENAI_API_KEY`, `openai-codex/gpt-5.5` для OAuth Codex через PI або -`openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативної оснастки -app-server Codex. +GPT-5.5 доступна як через прямий доступ за ключем API OpenAI Platform, так і через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для OAuth Codex через PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативної обв’язки Codex app-server. -Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не -вмикає вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише -коли ви явно вибираєте нативну оснастку Codex за допомогою -`agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`. -Якщо вбудований Plugin `codex` увімкнено, але `openai-codex/*` усе одно розв’язується -через PI, `openclaw doctor` попереджає і залишає маршрут без змін. +Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише тоді, коли ви явно вибираєте нативну обв’язку Codex за допомогою `agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`. +Якщо вбудований Plugin `codex` увімкнено, але `openai-codex/*` усе ще визначається через PI, `openclaw doctor` попереджає і залишає маршрут без змін. -## Покриття функцій OpenClaw +## Покриття можливостей OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Статус | +| Можливість OpenAI | Поверхня OpenClaw | Статус | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -| Чат / Responses | провайдер моделей `openai/` | Так | +| Чат / Responses | Провайдер моделей `openai/` | Так | | Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Оснастка app-server Codex | `openai/` з `agentRuntime.id: codex` | Так | +| Обв’язка Codex app-server | `openai/` з `agentRuntime.id: codex` | Так | | Серверний вебпошук | Нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдер не закріплено | | Зображення | `image_generate` | Так | | Відео | `video_generate` | Так | -| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | -| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | -| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | +| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так | +| Пакетне speech-to-text | `tools.media.audio` / розуміння медіа | Так | +| Потокове speech-to-text | Voice Call `streaming.provider: "openai"` | Так | | Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Вбудовування | провайдер вбудовувань пам’яті | Так | +| Embeddings | Провайдер embedding для пам’яті | Так | -## Вбудовування пам’яті +## Embeddings пам’яті -OpenClaw може використовувати OpenAI або OpenAI-сумісну кінцеву точку вбудовувань для -індексування `memory_search` і вбудовувань запитів: +OpenClaw може використовувати OpenAI або сумісний з OpenAI endpoint embeddings для індексації `memory_search` і embeddings запитів: ```json5 { @@ -111,11 +93,7 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс } ``` -Для OpenAI-сумісних кінцевих точок, які потребують асиметричних міток вбудовування, задайте -`queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає -їх як специфічні для провайдера поля запиту `input_type`: вбудовування запитів використовують -`queryInputType`; індексовані фрагменти пам’яті та пакетне індексування використовують -`documentInputType`. Повний приклад дивіться в [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config). +Для сумісних з OpenAI endpoint, які потребують асиметричних міток embeddings, задайте `queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає їх як специфічні для провайдера поля запиту `input_type`: embeddings запитів використовують `queryInputType`; проіндексовані фрагменти пам’яті та пакетна індексація використовують `documentInputType`. Повний приклад див. у [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config). ## Початок роботи @@ -129,7 +107,7 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс Створіть або скопіюйте ключ API з [панелі OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -149,17 +127,14 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ### Підсумок маршруту - | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | + | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | | ---------------------- | -------------------------- | --------------------------- | ---------------- | - | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Оснастка app-server Codex | app-server Codex | + | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Codex app-server | - `openai/*` — це прямий маршрут ключа API OpenAI, якщо ви явно не примушуєте - оснастку app-server Codex. Використовуйте `openai-codex/*` для OAuth Codex через - стандартний runner PI або використовуйте `openai/gpt-5.5` з - `agentRuntime.id: "codex"` для нативного виконання app-server Codex. + `openai/*` — це прямий маршрут ключа API OpenAI, якщо ви явно не примусите використання обв’язки Codex app-server. Використовуйте `openai-codex/*` для OAuth Codex через стандартний runner PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативного виконання Codex app-server. ### Приклад конфігурації @@ -178,7 +153,7 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Хмара Codex потребує входу в ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Codex cloud потребує входу ChatGPT. @@ -192,13 +167,13 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс openclaw models auth login --provider openai-codex ``` - Для headless або несумісних із callback налаштувань додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost: + Для headless-середовищ або налаштувань, де callback незручний, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` @@ -212,17 +187,15 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ### Підсумок маршруту - | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | + | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | |-----------|----------------|-------|------| | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex | | `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | Все ще PI, якщо Plugin явно не заявляє `openai-codex` | Вхід Codex | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Оснастка app-server Codex | Автентифікація app-server Codex | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо Plugin явно не оголошує `openai-codex` | Вхід Codex | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Автентифікація Codex app-server | - Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд автентифікації/профілю. Префікс - моделі `openai-codex/*` також є явним маршрутом PI для OAuth Codex. - Він не вибирає і не вмикає автоматично вбудовану оснастку app-server Codex. + Продовжуйте використовувати id провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для OAuth Codex. Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server. ### Приклад конфігурації @@ -234,35 +207,35 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ``` - Онбординг більше не імпортує OAuth-матеріал із `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. + Onboarding більше не імпортує матеріал OAuth з `~/.codex`. Увійдіть через OAuth у браузері (стандартно) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. ### Індикатор статусу Chat `/status` показує, яке середовище виконання моделі активне для поточного сеансу. - Стандартний PI harness відображається як `Runtime: OpenClaw Pi Default`. Коли вибрано - вбудований harness Codex app-server, `/status` показує - `Runtime: OpenAI Codex`. Наявні сеанси зберігають свій записаний ідентифікатор harness, тому використовуйте + Стандартна обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли вибрано + вбудовану обв’язку Codex app-server, `/status` показує + `Runtime: OpenAI Codex`. Наявні сеанси зберігають записаний ідентифікатор обв’язки, тому використовуйте `/new` або `/reset` після зміни `agentRuntime`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. ### Попередження Doctor - Якщо вбудований plugin `codex` увімкнено, а маршрут - `openai-codex/*` цієї вкладки вибрано, `openclaw doctor` попереджає, що модель - усе ще розв’язується через PI. Залиште конфігурацію без змін, коли це - очікуваний маршрут автентифікації через підписку. Перемикайтеся на `openai/` плюс - `agentRuntime.id: "codex"` лише тоді, коли потрібне нативне виконання Codex - app-server. + Якщо вбудований Plugin `codex` увімкнено, коли вибрано маршрут + `openai-codex/*` цієї вкладки, `openclaw doctor` попереджає, що модель + досі визначається через PI. Залиште конфігурацію без змін, якщо це + очікуваний маршрут автентифікації за підпискою. Перемикайтеся на `openai/` плюс + `agentRuntime.id: "codex"` лише тоді, коли потрібне нативне виконання + Codex app-server. ### Обмеження контекстного вікна - OpenClaw трактує метадані моделі та обмеження контексту середовища виконання як окремі значення. + OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення. Для `openai-codex/gpt-5.5` через Codex OAuth: - Нативний `contextWindow`: `1000000` - - Стандартне обмеження runtime `contextTokens`: `272000` + - Стандартне обмеження `contextTokens` середовища виконання: `272000` Менше стандартне обмеження на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: @@ -279,15 +252,15 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime. + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання. ### Відновлення каталогу OpenClaw використовує метадані upstream-каталогу Codex для `gpt-5.5`, коли вони - присутні. Якщо live-виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, тоді як - обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб - cron, sub-agent і запуски з налаштованою стандартною моделлю не завершувалися помилкою + наявні. Якщо live-виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, коли + обліковий запис автентифіковано, OpenClaw синтезує цей рядок моделі OAuth, щоб + cron, субагент і запуски зі сконфігурованою стандартною моделлю не завершувалися помилкою `Unknown model`. @@ -295,8 +268,8 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ## Нативна автентифікація Codex app-server -Нативний harness Codex app-server використовує посилання на моделі `openai/*` плюс -`agentRuntime.id: "codex"`, але його автентифікація все одно базується на обліковому записі. OpenClaw +Нативна обв’язка Codex app-server використовує посилання на моделі `openai/*` плюс +`agentRuntime.id: "codex"`, але її автентифікація все одно прив’язана до облікового запису. OpenClaw вибирає автентифікацію в такому порядку: 1. Явний профіль автентифікації OpenClaw `openai-codex`, прив’язаний до агента. @@ -305,29 +278,29 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс `OPENAI_API_KEY`, коли app-server повідомляє, що облікового запису немає, але все ще потребує автентифікації OpenAI. -Це означає, що локальний вхід через підписку ChatGPT/Codex не замінюється лише -тому, що процес gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI -або embeddings. Резервне використання API-ключа з env застосовується лише до локального stdio-шляху без облікового запису; він +Це означає, що локальний вхід за підпискою ChatGPT/Codex не замінюється лише +через те, що процес Gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI +або embeddings. Резервний env API-ключ використовується лише для локального stdio-шляху без облікового запису; він не надсилається до WebSocket-з’єднань app-server. Коли вибрано профіль Codex -у стилі підписки, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY` +підпискового типу, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY` у породжений дочірній процес stdio app-server і надсилає вибрані облікові дані -через login RPC app-server. +через RPC входу app-server. -## Генерація зображень +## Генерування зображень -Вбудований plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію зображень через Codex OAuth +Вбудований Plugin `openai` реєструє генерування зображень через інструмент `image_generate`. +Він підтримує як генерування зображень за API-ключем OpenAI, так і генерування зображень через Codex OAuth через те саме посилання на модель `openai/gpt-image-2`. | Можливість | API-ключ OpenAI | Codex OAuth | -| ------------------------- | ---------------------------------- | ------------------------------------ | -| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | Вхід OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | Бекенд Codex Responses | -| Макс. зображень на запит | 4 | 4 | -| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | -| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | Підтримується, зокрема розміри 2K/4K | -| Співвідношення сторін / роздільна здатність | Не пересилається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | +| ------------------------ | ---------------------------------- | ------------------------------------ | +| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | +| Автентифікація | `OPENAI_API_KEY` | Вхід через OpenAI Codex OAuth | +| Транспорт | OpenAI Images API | Backend Codex Responses | +| Макс. зображень на запит | 4 | 4 | +| Режим редагування | Увімкнено (до 5 референсних зображень) | Увімкнено (до 5 референсних зображень) | +| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | Підтримується, зокрема розміри 2K/4K | +| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | ```json5 { @@ -340,24 +313,24 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ``` -Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерування зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. -`gpt-image-2` є стандартним варіантом як для генерації зображень із тексту OpenAI, так і для -редагування зображень. `gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються придатними для використання як -явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виведення PNG/WebP -із прозорим фоном; поточний API `gpt-image-2` відхиляє +`gpt-image-2` є стандартним для генерування зображень із тексту OpenAI і для редагування зображень. +`gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` лишаються доступними як +явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу +PNG/WebP із прозорим фоном; поточний API `gpt-image-2` відхиляє `background: "transparent"`. Для запиту з прозорим фоном агенти мають викликати `image_generate` з `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` або `"webp"` і `background: "transparent"`; старіший параметр провайдера `openai.background` -все ще приймається. OpenClaw також захищає публічні маршрути OpenAI та +досі приймається. OpenClaw також захищає публічні маршрути OpenAI та OpenAI Codex OAuth, переписуючи стандартні прозорі запити `openai/gpt-image-2` на `gpt-image-1.5`; Azure і власні OpenAI-сумісні endpoints зберігають -свої налаштовані назви deployment/model. +сконфігуровані назви deployment/моделей. -Той самий параметр доступний для headless CLI-запусків: +Той самий параметр доступний для headless-запусків CLI: ```bash openclaw infer image generate \ @@ -370,18 +343,18 @@ openclaw infer image generate \ Використовуйте ті самі прапорці `--output-format` і `--background` з `openclaw infer image edit`, коли починаєте з вхідного файлу. -`--openai-background` залишається доступним як OpenAI-специфічний alias. +`--openai-background` лишається доступним як специфічний для OpenAI псевдонім. -Для встановлень Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли налаштовано -OAuth-профіль `openai-codex`, OpenClaw розв’язує збережений OAuth -access token і надсилає запити зображень через бекенд Codex Responses. Він +Для встановлень Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли +налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає збережений access token OAuth +і надсилає запити зображень через backend Codex Responses. Він спершу не пробує `OPENAI_API_KEY` і не виконує тихий fallback до API-ключа для цього запиту. Налаштуйте `models.providers.openai` явно з API-ключем, -власним базовим URL або Azure endpoint, коли потрібен прямий маршрут OpenAI Images API +власною базовою URL-адресою або endpoint Azure, коли потрібен прямий маршрут OpenAI Images API натомість. -Якщо цей власний image endpoint розташований у довіреній LAN/приватній адресі, також задайте +Якщо цей власний endpoint зображень розташований у довіреній LAN/приватній адресі, також задайте `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw залишає -приватні/внутрішні OpenAI-сумісні image endpoints заблокованими, якщо цього opt-in +приватні/внутрішні OpenAI-сумісні endpoints зображень заблокованими, якщо цього opt-in немає. Згенерувати: @@ -402,16 +375,16 @@ access token і надсилає запити зображень через бе /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` -## Генерація відео +## Генерування відео -Вбудований plugin `openai` реєструє генерацію відео через інструмент `video_generate`. +Вбудований Plugin `openai` реєструє генерування відео через інструмент `video_generate`. | Можливість | Значення | | ---------------- | --------------------------------------------------------------------------------- | -| Стандартна модель | `openai/sora-2` | +| Стандартна модель | `openai/sora-2` | | Режими | Текст-у-відео, зображення-у-відео, редагування одного відео | -| Еталонні вхідні дані | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Референсні вхідні дані | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -425,22 +398,22 @@ access token і надсилає запити зображень через бе ``` -Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерування відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. -## Внесок у промпт GPT-5 +## Внесок GPT-5 у prompt -OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x не отримують його. +OpenClaw додає спільний внесок GPT-5 у prompt для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x не отримують. -Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і overlay heartbeat через developer instructions Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови щодо доведення до кінця та проактивного heartbeat, навіть хоча рештою harness-промпта володіє Codex. +Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції розробника Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови щодо доведення справ до кінця й проактивного Heartbeat, хоча рештою prompt обв’язки керує Codex. -Внесок GPT-5 додає тегований контракт поведінки для сталості persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Канально-специфічна поведінка відповідей і silent-message залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Дружній шар interaction-style є окремим і налаштовуваним. +Внесок GPT-5 додає тегований контракт поведінки для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей, специфічна для каналу, і поведінка silent-message лишаються у спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди увімкнені для відповідних моделей. Дружній шар стилю взаємодії є окремим і налаштовуваним. | Значення | Ефект | -| ---------------------- | ------------------------------------------- | -| `"friendly"` (стандартно) | Увімкнути дружній шар interaction-style | -| `"on"` | Alias для `"friendly"` | -| `"off"` | Вимкнути лише дружній style layer | +| --------------------- | ------------------------------------------ | +| `"friendly"` (стандартно) | Увімкнути дружній шар стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише дружній шар стилю | @@ -464,31 +437,34 @@ OpenClaw додає спільний внесок у промпт GPT-5 для -Значення не чутливі до регістру під час виконання, тому `"Off"` і `"off"` обидва вимикають дружній style layer. +Значення не чутливі до регістру під час виконання, тому `"Off"` і `"off"` обидва вимикають дружній шар стилю. -Застарілий `plugins.entries.openai.config.personality` все ще читається як compatibility fallback, коли спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не встановлено. +Застарілий `plugins.entries.openai.config.personality` досі читається як fallback сумісності, коли спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення - Вбудований plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. + Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. | Параметр | Шлях конфігурації | Стандартно | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | - | Швидкість | `messages.tts.providers.openai.speed` | (не встановлено) | - | Інструкції | `messages.tts.providers.openai.instructions` | (не встановлено, лише `gpt-4o-mini-tts`) | + | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | + | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | API-ключ | `messages.tts.providers.openai.apiKey` | Fallback до `OPENAI_API_KEY` | - | Базовий URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | API-ключ | `messages.tts.providers.openai.apiKey` | fallback до `OPENAI_API_KEY` | + | Базова URL-адреса | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | Додаткове тіло | `messages.tts.providers.openai.extraBody` / `extra_body` | (не задано) | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. + `extraBody` об’єднується з JSON запиту `/audio/speech` після згенерованих OpenClaw полів, тому використовуйте його для OpenAI-сумісних endpoints, які потребують додаткових ключів, як-от `lang`. Prototype-ключі ігноруються. + ```json5 { messages: { @@ -502,23 +478,23 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ``` - Задайте `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на endpoint chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS, не впливаючи на endpoint chat API. - - Вбудований plugin `openai` реєструє пакетне speech-to-text через + + Вбудований Plugin `openai` реєструє пакетне перетворення мовлення в текст через поверхню транскрипції media-understanding OpenClaw. - Стандартна модель: `gpt-4o-transcribe` - - Endpoint: OpenAI REST `/v1/audio/transcriptions` - - Шлях введення: завантаження multipart audio file - - Підтримується OpenClaw скрізь, де транскрипція вхідного audio використовує - `tools.media.audio`, зокрема сегменти голосових каналів Discord і канальні - audio attachments + - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` + - Шлях введення: завантаження аудіофайлу multipart + - Підтримується OpenClaw усюди, де транскрибування вхідного аудіо використовує + `tools.media.audio`, зокрема сегменти голосових каналів Discord і + аудіовкладення каналів - Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо: + Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: ```json5 { @@ -538,53 +514,53 @@ OpenClaw додає спільний внесок у промпт GPT-5 для } ``` - Підказки щодо мови та промпту передаються до OpenAI, коли їх надано через - спільну конфігурацію аудіомедіа або запит транскрипції для окремого виклику. + Підказки щодо мови та промпта передаються до OpenAI, коли їх надає + спільна конфігурація аудіомедіа або запит транскрибування окремого виклику. - - Вбудований Plugin `openai` реєструє транскрипцію в реальному часі для Plugin Voice Call. + + Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | Стандартне значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | - | Мова | `...openai.language` | (не задано) | - | Промпт | `...openai.prompt` | (не задано) | + | Мова | `...openai.language` | (не встановлено) | + | Промпт | `...openai.prompt` | (не встановлено) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | - Використовує WebSocket-з'єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий provider призначений для шляху транскрипції в реальному часі Voice Call; голос Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрипції `tools.media.audio`. + Використовує з'єднання WebSocket із `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі Voice Call; голос Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрибування `tools.media.audio`. - + Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | Стандартне значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Температура | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | - Підтримує Azure OpenAI через конфігураційні ключі `azureEndpoint` і `azureDeployment` для бекенд-мостів реального часу. Підтримує двонапрямні виклики інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для серверних мостів реального часу. Підтримує двоспрямовані виклики інструментів. Використовує аудіоформат G.711 u-law. - Talk в Control UI використовує браузерні сесії OpenAI у реальному часі з - ефемерним клієнтським секретом, згенерованим Gateway, і прямим браузерним обміном WebRTC SDP з - OpenAI Realtime API. Підтримувачі можуть виконати live-перевірку за допомогою + Control UI Talk використовує браузерні сесії OpenAI у реальному часі з + ефемерним клієнтським секретом, створеним Gateway, і прямим браузерним обміном WebRTC SDP з + OpenAI Realtime API. Жива перевірка для супровідників доступна через `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`; - гілка OpenAI створює клієнтський секрет у Node, генерує браузерну SDP-пропозицію - з фіктивним мікрофонним медіа, надсилає її до OpenAI й застосовує SDP-відповідь - без журналювання секретів. + гілка OpenAI створює клієнтський секрет у Node, генерує браузерну пропозицію SDP + з фейковим мікрофонним медіа, надсилає її до OpenAI і застосовує відповідь SDP + без логування секретів. @@ -592,29 +568,29 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ## Кінцеві точки Azure OpenAI -Вбудований provider `openai` може націлюватися на ресурс Azure OpenAI для генерації +Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для генерації зображень через перевизначення базової URL-адреси. На шляху генерації зображень OpenClaw виявляє імена хостів Azure у `models.providers.openai.baseUrl` і автоматично перемикається на -формат запиту Azure. +форму запиту Azure. Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і не залежить від `models.providers.openai.baseUrl`. Дивіться accordion **Realtime -voice** у розділі [Голос і мовлення](#voice-and-speech) щодо його налаштувань Azure. +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному +часі** в розділі [Голос і мовлення](#voice-and-speech) щодо його налаштувань Azure. Використовуйте Azure OpenAI, коли: - У вас уже є підписка Azure OpenAI, квота або корпоративна угода - Вам потрібні регіональне розміщення даних або засоби контролю відповідності, які надає Azure -- Ви хочете тримати трафік у межах наявного тенанта Azure +- Ви хочете залишити трафік усередині наявного тенанта Azure ### Конфігурація -Для генерації зображень Azure через вбудований provider `openai` вкажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як -ключ Azure OpenAI (а не ключ OpenAI Platform): +Для генерації зображень Azure через вбудований провайдер `openai` спрямуйте +`models.providers.openai.baseUrl` на свій ресурс Azure і встановіть `apiKey` як +ключ Azure OpenAI (не ключ OpenAI Platform): ```json5 { @@ -639,47 +615,47 @@ Azure: Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи, прив'язані до deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи з областю deployment (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -- Використовує типовий тайм-аут запиту 600 с для викликів генерації зображень Azure. - Значення `timeoutMs` для окремих викликів усе ще перевизначають це типове значення. +- Використовує стандартний тайм-аут запиту 600 с для викликів генерації зображень Azure. + Значення `timeoutMs` для окремого виклику й далі перевизначають це стандартне значення. -Інші базові URL-адреси (публічний OpenAI, проксі, сумісні з OpenAI) зберігають стандартний -формат запиту зображень OpenAI. +Інші базові URL-адреси (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну +форму запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень provider `openai` потребує -OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який власний +Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує +OpenClaw 2026.4.22 або новішої версії. Раніші версії обробляють будь-який користувацький `openai.baseUrl` як публічну кінцеву точку OpenAI і завершаться помилкою з deployment зображень Azure. ### Версія API -Задайте `AZURE_OPENAI_API_VERSION`, щоб закріпити конкретну preview- або GA-версію Azure +Встановіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure для шляху генерації зображень Azure: ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типове значення — `2024-12-01-preview`, коли змінну не задано. +Стандартне значення — `2024-12-01-preview`, коли змінну не встановлено. ### Назви моделей є назвами deployment Azure OpenAI прив'язує моделі до deployment. Для запитів генерації зображень Azure, -маршрутизованих через вбудований provider `openai`, поле `model` в OpenClaw -має бути **назвою Azure deployment**, яку ви налаштували на порталі Azure, а не +маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw +має бути **назвою deployment Azure**, яку ви налаштували на порталі Azure, а не ідентифікатором публічної моделі OpenAI. -Якщо ви створюєте deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: +Якщо ви створюєте deployment із назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` Те саме правило назви deployment застосовується до викликів генерації зображень, -маршрутизованих через вбудований provider `openai`. +маршрутизованих через вбудований провайдер `openai`. ### Регіональна доступність @@ -695,35 +671,35 @@ Azure може відхиляти параметри, які дозволяє п значення `background` для `gpt-image-2`), або надавати їх лише для конкретних версій моделі. Ці відмінності походять від Azure і базової моделі, а не від OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте -набір параметрів, який підтримує ваш конкретний deployment і версія API, на +набір параметрів, який підтримують ваш конкретний deployment і версія API на порталі Azure. Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує -приховані заголовки атрибуції OpenClaw — дивіться accordion **Native vs OpenAI-compatible -routes** у розділі [Розширена конфігурація](#advanced-configuration). +прихованих заголовків атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні +маршрути** в розділі [Розширена конфігурація](#advanced-configuration). Для трафіку chat або Responses в Azure (поза генерацією зображень) використовуйте -процес onboarding або окрему конфігурацію provider Azure — самого `openai.baseUrl` -недостатньо, щоб застосувати формат API/auth Azure. Існує окремий -provider `azure-openai-responses/*`; дивіться accordion про серверну Compaction нижче. +процес onboarding або спеціальну конфігурацію провайдера Azure — самого лише +`openai.baseUrl` недостатньо, щоб застосувати форму Azure API/auth. Існує окремий +провайдер `azure-openai-responses/*`; див. акордеон Server-side compaction нижче. ## Розширена конфігурація - - OpenClaw використовує WebSocket-first із резервним SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + + OpenClaw використовує WebSocket як пріоритетний варіант із запасним SSE (`"auto"`) для `openai/*` і `openai-codex/*`. У режимі `"auto"` OpenClaw: - - Повторює одну ранню помилку WebSocket перед переходом на SSE + - Повторює одну ранню невдалу спробу WebSocket перед переходом на SSE - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - - Додає стабільні заголовки ідентичності сесії та turn для повторів і перепідключень + - Додає стабільні заголовки ідентичності сесії та turn для повторних спроб і повторних підключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | Спочатку WebSocket, резервно SSE | + | `"auto"` (стандартно) | Спочатку WebSocket, SSE як запасний варіант | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -750,8 +726,8 @@ provider `azure-openai-responses/*`; дивіться accordion про серв - - OpenClaw вмикає warm-up WebSocket за замовчуванням для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого turn. + + OpenClaw стандартно вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого turn. ```json5 // Disable warm-up @@ -770,13 +746,13 @@ provider `azure-openai-responses/*`; дивіться accordion про серв - + OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - **Chat/UI:** `/fast status|on|off` - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. + Коли його ввімкнено, OpenClaw відображає швидкий режим на пріоритетну обробку OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. ```json5 { @@ -791,13 +767,13 @@ provider `azure-openai-responses/*`; дивіться accordion про серв ``` - Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в Sessions UI повертає сесію до налаштованого типового значення. + Перевизначення сесії мають перевагу над конфігурацією. Очищення перевизначення сесії в Sessions UI повертає сесію до налаштованого стандартного значення. - - API OpenAI надає пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw: + + API OpenAI надає пріоритетну обробку через `service_tier`. Встановіть її для кожної моделі в OpenClaw: ```json5 { @@ -814,22 +790,22 @@ provider `azure-openai-responses/*`; дивіться accordion про серв Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-який provider через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з провайдерів через проксі, OpenClaw залишає `service_tier` без змін. - + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) потокова обгортка Pi-harness Plugin OpenAI автоматично вмикає серверну Compaction: - - Примусово задає `store: true` (якщо model compat не задає `supportsStore: false`) + - Примусово встановлює `store: true` (якщо model compat не встановлює `supportsStore: false`) - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно) + - Стандартне значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно) - Це застосовується до вбудованого шляху Pi harness і до хуків provider OpenAI, які використовують embedded runs. Нативний harness сервера застосунку Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`. + Це застосовується до вбудованого шляху Pi harness і до hooks провайдера OpenAI, які використовують вбудовані запуски. Нативний app-server harness Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`. - + Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses: ```json5 @@ -846,7 +822,7 @@ provider `azure-openai-responses/*`; дивіться accordion про серв } ``` - + ```json5 { agents: { @@ -864,7 +840,7 @@ provider `azure-openai-responses/*`; дивіться accordion про серв } ``` - + ```json5 { agents: { @@ -882,13 +858,13 @@ provider `azure-openai-responses/*`; дивіться accordion про серв - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses все одно примусово використовують `store: true`, якщо compat не встановлює `supportsStore: false`. + `responsesServerCompaction` керує лише інʼєкцією `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо шар сумісності не встановлює `supportsStore: false`. - - Для запусків родини GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання: + + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати строгіший вбудований контракт виконання: ```json5 { @@ -902,34 +878,34 @@ provider `azure-openai-responses/*`; дивіться accordion про серв З `strict-agentic` OpenClaw: - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - - Повторює хід із підказкою діяти негайно + - Повторює хід зі скеровуванням діяти зараз - Автоматично вмикає `update_plan` для суттєвої роботи - Показує явний заблокований стан, якщо модель продовжує планувати без дій - Застосовується лише до запусків OpenAI і Codex родини GPT-5. Інші провайдери та старіші родини моделей зберігають типову поведінку. + Обмежено лише запусками сімейства OpenAI і Codex GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж загальні OpenAI-сумісні проксі `/v1`: + OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж універсальні OpenAI-сумісні проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують рівень зусилля OpenAI `none` - - Пропускають вимкнене reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово використовують суворий режим для схем інструментів + - Зберігають `reasoning: { effort: "none" }` лише для моделей, що підтримують рівень зусиль OpenAI `none` + - Пропускають вимкнене міркування для моделей або проксі, які відхиляють `reasoning.effort: "none"` + - Типово використовують строгий режим для схем інструментів - Додають приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache) + - Зберігають формування запитів, специфічне лише для OpenAI (`service_tier`, `store`, сумісність міркування, підказки кешу промптів) **Проксі/сумісні маршрути:** - - Використовують м’якшу compat-поведінку - - Вилучають Completions `store` з ненативних payload `openai-completions` - - Приймають наскрізний JSON `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions + - Використовують вільнішу поведінку сумісності + - Вилучають Completions `store` з ненативних корисних навантажень `openai-completions` + - Приймають розширений наскрізний JSON `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions - Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, таких як vLLM - - Не примушують суворі схеми інструментів або лише нативні заголовки + - Не примушують строгі схеми інструментів або лише нативні заголовки - Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує прихованих заголовків атрибуції. + Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції. @@ -938,7 +914,7 @@ provider `azure-openai-responses/*`; дивіться accordion про серв - Вибір провайдерів, посилань на моделі та поведінки резервного перемикання. + Вибір провайдерів, посилань на моделі та поведінки відновлення після збою. Спільні параметри інструмента зображень і вибір провайдера. @@ -947,6 +923,6 @@ provider `azure-openai-responses/*`; дивіться accordion про серв Спільні параметри інструмента відео та вибір провайдера. - Відомості про автентифікацію та правила повторного використання облікових даних. + Подробиці автентифікації та правила повторного використання облікових даних. diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index d54091145..78dd6ded4 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,37 +1,37 @@ --- read_when: - - Увімкнення text-to-speech для відповідей - - Налаштування провайдера TTS, ланцюжка fallback або персони - - Використання команд або директив `/tts` + - Увімкнення перетворення тексту на мовлення для відповідей + - Налаштування провайдера TTS, ланцюжка резервного перемикання або персони + - Використання команд або директив /tts sidebarTitle: Text to speech (TTS) -summary: Text-to-speech для вихідних відповідей — провайдери, персони, slash-команди та вивід для кожного каналу -title: Text-to-speech +summary: Перетворення тексту на мовлення для вихідних відповідей — провайдери, персони, slash-команди та виведення для кожного каналу +title: Перетворення тексту на мовлення x-i18n: - generated_at: "2026-04-28T00:36:16Z" - model: gpt-5.4 + generated_at: "2026-05-01T22:03:36Z" + model: gpt-5.5 provider: openai - source_hash: ec58d19fbca0ff0cd9828f32c150123cad22f053a6b4281ed40ec3d1fa41d1b2 + source_hash: 8ff736249314fcfbc4f61c24a9c005c02e3582e2aa5fe0baac7e99c5e00f15e1 source_path: tools/tts.md - workflow: 15 + workflow: 16 --- -OpenClaw може перетворювати вихідні відповіді на аудіо через **14 speech-провайдерів** -і доставляти нативні голосові повідомлення у Feishu, Matrix, Telegram і WhatsApp, -аудіовкладення всюди в інших місцях, а також потоки PCM/Ulaw для телефонії та Talk. +OpenClaw може перетворювати вихідні відповіді на аудіо через **14 провайдерів мовлення** +і надсилати нативні голосові повідомлення у Feishu, Matrix, Telegram і WhatsApp, +аудіовкладення в усіх інших каналах, а також потоки PCM/Ulaw для телефонії та Talk. ## Швидкий старт - OpenAI та ElevenLabs — найнадійніші хостингові варіанти. Microsoft і - Local CLI працюють без API-ключа. Повний список дивіться в [матриці провайдерів](#supported-providers). + OpenAI і ElevenLabs — найнадійніші хостингові варіанти. Microsoft і + Local CLI працюють без ключа API. Повний список див. у [матриці провайдерів](#supported-providers). - - Експортуйте env-змінну для вашого провайдера (наприклад, `OPENAI_API_KEY`, - `ELEVENLABS_API_KEY`). Для Microsoft і Local CLI ключ не потрібен. + + Експортуйте змінну середовища для вашого провайдера (наприклад `OPENAI_API_KEY`, + `ELEVENLABS_API_KEY`). Microsoft і Local CLI не потребують ключа. - Установіть `messages.tts.auto: "always"` і `messages.tts.provider`: + Задайте `messages.tts.auto: "always"` і `messages.tts.provider`: ```json5 { @@ -52,47 +52,47 @@ OpenClaw може перетворювати вихідні відповіді -Auto-TTS **вимкнено** за замовчуванням. Коли `messages.tts.provider` не задано, -OpenClaw вибирає першого налаштованого провайдера в порядку auto-select реєстру. +Auto-TTS за замовчуванням **вимкнено**. Коли `messages.tts.provider` не задано, +OpenClaw вибирає першого налаштованого провайдера в порядку автоматичного вибору реєстру. ## Підтримувані провайдери -| Провайдер | Auth | Примітки | -| ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (також `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`) | Нативний вивід голосових нотаток Ogg/Opus і телефонії. | -| **DeepInfra** | `DEEPINFRA_API_KEY` | TTS, сумісний з OpenAI. За замовчуванням `hexgrad/Kokoro-82M`. | -| **ElevenLabs** | `ELEVENLABS_API_KEY` або `XI_API_KEY` | Клонування голосу, багатомовність, детермінованість через `seed`. | -| **Google Gemini** | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | TTS Gemini API; підтримує персони через `promptTemplate: "audio-profile-v1"`. | -| **Gradium** | `GRADIUM_API_KEY` | Вивід голосових нотаток і телефонії. | -| **Inworld** | `INWORLD_API_KEY` | Streaming TTS API. Нативний Opus для голосових нотаток і PCM для телефонії. | -| **Local CLI** | none | Запускає налаштовану локальну команду TTS. | -| **Microsoft** | none | Публічний Edge neural TTS через `node-edge-tts`. Best-effort, без SLA. | -| **MiniMax** | `MINIMAX_API_KEY` (або Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`) | API T2A v2. За замовчуванням `speech-2.8-hd`. | -| **OpenAI** | `OPENAI_API_KEY` | Також використовується для auto-summary; підтримує персону `instructions`. | -| **OpenRouter** | `OPENROUTER_API_KEY` (може повторно використовувати `models.providers.openrouter.apiKey`) | Типова модель `hexgrad/kokoro-82m`. | -| **Volcengine** | `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY` (застарілі AppID/token: `VOLCENGINE_TTS_APPID`/`_TOKEN`) | HTTP API BytePlus Seed Speech. | -| **Vydra** | `VYDRA_API_KEY` | Спільний провайдер зображень, відео та мовлення. | -| **xAI** | `XAI_API_KEY` | Пакетний TTS xAI. Нативний Opus для голосових нотаток **не** підтримується. | -| **Xiaomi MiMo** | `XIAOMI_API_KEY` | TTS MiMo через chat completions Xiaomi. | +| Провайдер | Авторизація | Примітки | +| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (також `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`) | Нативний вивід голосових нотаток Ogg/Opus і телефонія. | +| **DeepInfra** | `DEEPINFRA_API_KEY` | TTS, сумісний з OpenAI. За замовчуванням `hexgrad/Kokoro-82M`. | +| **ElevenLabs** | `ELEVENLABS_API_KEY` або `XI_API_KEY` | Клонування голосу, багатомовність, детермінованість через `seed`. | +| **Google Gemini** | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | TTS Gemini API; враховує персону через `promptTemplate: "audio-profile-v1"`. | +| **Gradium** | `GRADIUM_API_KEY` | Вивід голосових нотаток і телефонії. | +| **Inworld** | `INWORLD_API_KEY` | API потокового TTS. Нативна голосова нотатка Opus і телефонія PCM. | +| **Local CLI** | немає | Запускає налаштовану локальну команду TTS. | +| **Microsoft** | немає | Публічний нейронний TTS Edge через `node-edge-tts`. Найкраще можливе, без SLA. | +| **MiniMax** | `MINIMAX_API_KEY` (або Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`) | API T2A v2. За замовчуванням `speech-2.8-hd`. | +| **OpenAI** | `OPENAI_API_KEY` | Також використовується для автопідсумку; підтримує `instructions` персони. | +| **OpenRouter** | `OPENROUTER_API_KEY` (може повторно використовувати `models.providers.openrouter.apiKey`) | Модель за замовчуванням `hexgrad/kokoro-82m`. | +| **Volcengine** | `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY` (застарілі AppID/token: `VOLCENGINE_TTS_APPID`/`_TOKEN`) | HTTP API BytePlus Seed Speech. | +| **Vydra** | `VYDRA_API_KEY` | Спільний провайдер зображень, відео й мовлення. | +| **xAI** | `XAI_API_KEY` | Пакетний TTS xAI. Нативна голосова нотатка Opus **не** підтримується. | +| **Xiaomi MiMo** | `XIAOMI_API_KEY` | MiMo TTS через чат-завершення Xiaomi. | -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний, -а інші стають fallback-варіантами. Auto-summary використовує `summaryModel` (або -`agents.defaults.model.primary`), тож якщо ви залишаєте summaries увімкненими, -цей провайдер також має бути автентифікований. +Якщо налаштовано кілька провайдерів, спочатку використовується вибраний, а +інші є резервними варіантами. Автопідсумок використовує `summaryModel` (або +`agents.defaults.model.primary`), тому цей провайдер також має бути автентифікований, +якщо ви залишаєте підсумки ввімкненими. -Вбудований провайдер **Microsoft** використовує онлайновий neural TTS-сервіс Microsoft Edge -через `node-edge-tts`. Це публічний вебсервіс без опублікованих -SLA або квот — вважайте його best-effort. Застарілий ідентифікатор провайдера `edge` +Вбудований провайдер **Microsoft** використовує онлайн-сервіс нейронного TTS Microsoft Edge +через `node-edge-tts`. Це публічний вебсервіс без опублікованого +SLA чи квоти — вважайте його сервісом без гарантованого результату. Застарілий ідентифікатор провайдера `edge` нормалізується до `microsoft`, а `openclaw doctor --fix` переписує збережену -конфігурацію; у нових конфігураціях завжди слід використовувати `microsoft`. +конфігурацію; нові конфігурації завжди мають використовувати `microsoft`. ## Конфігурація -Конфігурація TTS розміщується в `messages.tts` у `~/.openclaw/openclaw.json`. Виберіть -preset і адаптуйте блок провайдера: +Конфігурація TTS зберігається в `messages.tts` у `~/.openclaw/openclaw.json`. Виберіть +пресет і адаптуйте блок провайдера: @@ -148,8 +148,8 @@ preset і адаптуйте блок провайдера: apiKey: "${GEMINI_API_KEY}", model: "gemini-3.1-flash-tts-preview", voiceName: "Kore", - // Необов’язкові запити стилю природною мовою: - // audioProfile: "Говори спокійним тоном ведучого подкасту.", + // Optional natural-language style prompts: + // audioProfile: "Speak in a calm, podcast-host tone.", // speakerName: "Alex", }, }, @@ -216,7 +216,7 @@ preset і адаптуйте блок провайдера: } ``` - + ```json5 { messages: { @@ -370,11 +370,11 @@ preset і адаптуйте блок провайдера: -### Перевизначення голосу для кожного agent +### Перевизначення голосу для окремого агента -Використовуйте `agents.list[].tts`, коли один agent має говорити з іншим провайдером, -голосом, моделлю, персоною або режимом auto-TTS. Блок agent виконує глибоке злиття поверх -`messages.tts`, тому облікові дані провайдера можуть залишатися в глобальній конфігурації провайдера: +Використовуйте `agents.list[].tts`, коли один агент має говорити з іншим провайдером, +голосом, моделлю, персоною або режимом автоматичного TTS. Блок агента глибоко зливається поверх +`messages.tts`, тож облікові дані провайдера можуть залишатися в глобальній конфігурації провайдера: ```json5 { @@ -402,23 +402,23 @@ preset і адаптуйте блок провайдера: } ``` -Щоб зафіксувати персону для конкретного agent, встановіть `agents.list[].tts.persona` разом із -конфігурацією провайдера — це перевизначає глобальне `messages.tts.persona` лише для цього agent. +Щоб закріпити персону для окремого агента, задайте `agents.list[].tts.persona` поруч із конфігурацією +провайдера — це перевизначає глобальну `messages.tts.persona` лише для цього агента. -Порядок пріоритету для автоматичних відповідей, `/tts audio`, `/tts status` і -інструмента agent `tts`: +Порядок пріоритету для автоматичних відповідей, `/tts audio`, `/tts status` та +інструмента агента `tts`: 1. `messages.tts` 2. активний `agents.list[].tts` 3. перевизначення каналу, коли канал підтримує `channels..tts` 4. перевизначення облікового запису, коли канал передає `channels..accounts..tts` -5. локальні налаштування `/tts` для цього host -6. вбудовані директиви `[[tts:...]]`, коли [керовані моделлю перевизначення](#model-driven-directives) увімкнено +5. локальні налаштування `/tts` для цього хоста +6. вбудовані директиви `[[tts:...]]`, коли ввімкнено [перевизначення, керовані моделлю](#model-driven-directives) -Перевизначення каналу й облікового запису використовують ту саму форму, що й `messages.tts`, і -виконують глибоке злиття поверх попередніх шарів, тому спільні облікові дані провайдера можуть залишатися в -`messages.tts`, тоді як канал або обліковий запис бота змінює лише voice, model, persona -або режим auto: +Перевизначення каналів і облікових записів використовують ту саму форму, що й `messages.tts`, і +глибоко зливаються поверх попередніх шарів, тому спільні облікові дані провайдера можуть залишатися в +`messages.tts`, тоді як канал або обліковий запис бота змінює лише голос, модель, персону +або автоматичний режим: ```json5 { @@ -448,10 +448,10 @@ preset і адаптуйте блок провайдера: ## Персони -**Персона** — це стабільна мовленнєва ідентичність, яку можна детерміновано -застосовувати в різних провайдерів. Вона може надавати перевагу одному провайдеру, визначати -нейтральний щодо провайдера намір prompt і містити прив’язки, специфічні для провайдера, для голосів, моделей, prompt- -templates, seeds і voice settings. +**Персона** — це стабільна мовлена ідентичність, яку можна детерміновано застосовувати +між провайдерами. Вона може віддавати перевагу одному провайдеру, визначати +провайдерно-нейтральний намір підказки та містити прив’язки, специфічні для провайдера: +голоси, моделі, шаблони підказок, зерна та налаштування голосу. ### Мінімальна персона @@ -463,7 +463,7 @@ templates, seeds і voice settings. persona: "narrator", personas: { narrator: { - label: "Оповідач", + label: "Narrator", provider: "elevenlabs", providers: { elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" }, @@ -475,7 +475,7 @@ templates, seeds і voice settings. } ``` -### Повна персона (нейтральний щодо провайдера prompt) +### Повна персона (провайдерно-нейтральна підказка) ```json5 { @@ -486,17 +486,17 @@ templates, seeds і voice settings. personas: { alfred: { label: "Alfred", - description: "Сухий, теплий британський голос оповідача-дворецького.", + description: "Dry, warm British butler narrator.", provider: "google", fallbackPolicy: "preserve-persona", prompt: { - profile: "Блискучий британський дворецький. Сухий, дотепний, теплий, чарівний, емоційно виразний, ніколи не загальний.", - scene: "Тихий пізньовечірній кабінет. Оповідь біля мікрофона для довіреного оператора.", - sampleContext: "Мовець відповідає на приватний технічний запит стисло, впевнено й із сухою теплотою.", - style: "Вишуканий, стриманий, з легкою усмішкою.", - accent: "Британська англійська.", - pacing: "Розмірений, із короткими драматичними паузами.", - constraints: ["Не зачитувати вголос значення конфігурації.", "Не пояснювати персону."], + profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.", + scene: "A quiet late-night study. Close-mic narration for a trusted operator.", + sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.", + style: "Refined, understated, lightly amused.", + accent: "British English.", + pacing: "Measured, with short dramatic pauses.", + constraints: ["Do not read configuration values aloud.", "Do not explain the persona."], }, providers: { google: { @@ -529,98 +529,98 @@ templates, seeds і voice settings. Активна персона вибирається детерміновано: -1. локальне налаштування `/tts persona `, якщо встановлено. -2. `messages.tts.persona`, якщо встановлено. -3. Персона відсутня. +1. Локальне налаштування `/tts persona `, якщо задано. +2. `messages.tts.persona`, якщо задано. +3. Без персони. -Вибір провайдера виконується за принципом explicit-first: +Вибір провайдера виконується за принципом явного пріоритету: -1. Прямі перевизначення (CLI, gateway, Talk, дозволені директиви TTS). +1. Прямі перевизначення (CLI, Gateway, Talk, дозволені директиви TTS). 2. Локальне налаштування `/tts provider `. 3. `provider` активної персони. 4. `messages.tts.provider`. -5. Auto-select реєстру. +5. Автовибір реєстру. -Для кожної спроби з провайдером OpenClaw об’єднує конфігурації в такому порядку: +Для кожної спроби провайдера OpenClaw зливає конфігурації в такому порядку: 1. `messages.tts.providers.` 2. `messages.tts.personas..providers.` 3. Довірені перевизначення запиту -4. Дозволені перевизначення директив TTS, згенерованих моделлю +4. Дозволені перевизначення директив TTS, згенеровані моделлю -### Як провайдери використовують prompt персони +### Як провайдери використовують підказки персони -Поля prompt персони (`profile`, `scene`, `sampleContext`, `style`, `accent`, -`pacing`, `constraints`) є **нейтральними щодо провайдера**. Кожен провайдер сам вирішує, як -їх використовувати: +Поля підказки персони (`profile`, `scene`, `sampleContext`, `style`, `accent`, +`pacing`, `constraints`) є **провайдерно-нейтральними**. Кожен провайдер вирішує, +як їх використовувати: - Обгортає поля prompt персони в структуру prompt Gemini TTS **лише коли** - ефективна конфігурація провайдера Google встановлює `promptTemplate: "audio-profile-v1"` - або `personaPrompt`. Старіші поля `audioProfile` і `speakerName` усе ще - додаються на початок як текст prompt, специфічний для Google. Вбудовані audio-теги, такі як + Обгортає поля підказки персони в структуру підказки Gemini TTS **лише тоді, коли** + ефективна конфігурація провайдера Google задає `promptTemplate: "audio-profile-v1"` + або `personaPrompt`. Старіші поля `audioProfile` і `speakerName` все ще + додаються на початок як специфічний для Google текст підказки. Вбудовані аудіотеги, як-от `[whispers]` або `[laughs]` усередині блоку `[[tts:text]]`, зберігаються - в transcript Gemini; OpenClaw не генерує ці теги. + в транскрипті Gemini; OpenClaw не генерує ці теги. - Відображає поля prompt персони в поле запиту `instructions` **лише коли** - не налаштовано явне `instructions` для OpenAI. Явне `instructions` - завжди має пріоритет. + Зіставляє поля підказки персони з полем запиту `instructions` **лише тоді, коли** + явні OpenAI `instructions` не налаштовано. Явні `instructions` + завжди мають пріоритет. - Використовують лише прив’язки персони, специфічні для провайдера, у - `personas..providers.`. Поля prompt персони ігноруються, - якщо провайдер не реалізує власне зіставлення persona-prompt. + Використовують лише специфічні для провайдера прив’язки персони в + `personas..providers.`. Поля підказки персони ігноруються, + якщо провайдер не реалізує власне зіставлення підказок персони. -### Політика fallback +### Політика резервного переходу `fallbackPolicy` керує поведінкою, коли персона **не має прив’язки** для -провайдера, що перевіряється: +провайдера, який пробують використати: | Політика | Поведінка | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `preserve-persona` | **За замовчуванням.** Нейтральні щодо провайдера поля prompt залишаються доступними; провайдер може використовувати їх або ігнорувати. | -| `provider-defaults` | Персона виключається з підготовки prompt для цієї спроби; провайдер використовує свої нейтральні значення за замовчуванням, поки fallback до інших провайдерів триває. | -| `fail` | Пропускає цю спробу провайдера з `reasonCode: "not_configured"` і `personaBinding: "missing"`. Fallback-провайдери все одно будуть перевірятися. | +| `preserve-persona` | **Типово.** Провайдерно-нейтральні поля підказки залишаються доступними; провайдер може використовувати їх або ігнорувати. | +| `provider-defaults` | Персона вилучається з підготовки підказки для цієї спроби; провайдер використовує свої нейтральні типові значення, поки резервний перехід до інших провайдерів триває. | +| `fail` | Пропустити цю спробу провайдера з `reasonCode: "not_configured"` і `personaBinding: "missing"`. Резервні провайдери все ще пробуються. | -Увесь запит TTS завершується помилкою лише тоді, коли **кожен** перевірений провайдер пропущено -або він завершився помилкою. +Увесь запит TTS завершується невдачею лише тоді, коли **кожну** спробу провайдера пропущено +або вона завершилась помилкою. ## Директиви, керовані моделлю -За замовчуванням assistant **може** виводити директиви `[[tts:...]]` для перевизначення -voice, model або speed для однієї відповіді, а також необов’язковий -блок `[[tts:text]]...[[/tts:text]]` для виразних підказок, які мають з’явитися +За замовчуванням помічник **може** виводити директиви `[[tts:...]]`, щоб перевизначити +голос, модель або швидкість для однієї відповіді, а також необов’язковий блок +`[[tts:text]]...[[/tts:text]]` для виразних підказок, які мають з’являтися лише в аудіо: ```text -Ось. +Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](сміється) Прочитай пісню ще раз.[[/tts:text]] +[[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` -Коли `messages.tts.auto` має значення `"tagged"`, для запуску -аудіо **обов’язково потрібні директиви**. Потокова доставка блоків прибирає директиви з видимого тексту до того, як -канал їх побачить, навіть якщо вони розбиті між сусідніми блоками. +Коли `messages.tts.auto` має значення `"tagged"`, **директиви обов’язкові** для запуску +аудіо. Потокова доставка блоків прибирає директиви з видимого тексту до того, як +канал їх побачить, навіть якщо вони розділені між сусідніми блоками. -`provider=...` ігнорується, якщо не встановлено `modelOverrides.allowProvider: true`. Коли +`provider=...` ігнорується, якщо `modelOverrides.allowProvider: true` не задано. Коли відповідь оголошує `provider=...`, інші ключі в цій директиві аналізуються -лише цим провайдером; непідтримувані ключі видаляються й повідомляються як попередження -директив TTS. +лише цим провайдером; непідтримувані ключі вилучаються й повідомляються як +попередження директив TTS. **Доступні ключі директив:** -- `provider` (ідентифікатор зареєстрованого провайдера; потребує `allowProvider: true`) +- `provider` (зареєстрований ідентифікатор провайдера; потребує `allowProvider: true`) - `voice` / `voiceName` / `voice_name` / `google_voice` / `voiceId` - `model` / `google_model` - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0–10) -- `pitch` (цілочисельний pitch MiniMax, від −12 до 12; дробові значення відкидаються) -- `emotion` (тег emotion у Volcengine) +- `pitch` (цілочисельна висота тону MiniMax, −12 до 12; дробові значення обрізаються) +- `emotion` (тег емоції Volcengine) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` @@ -631,7 +631,7 @@ voice, model або speed для однієї відповіді, а також { messages: { tts: { modelOverrides: { enabled: false } } } } ``` -**Дозволити перемикання провайдера, залишаючи інші параметри налаштовуваними:** +**Дозволити перемикання провайдера, зберігаючи інші регулятори налаштовуваними:** ```json5 { messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } } @@ -639,8 +639,8 @@ voice, model або speed для однієї відповіді, а також ## Slash-команди -Єдина команда `/tts`. У Discord OpenClaw також реєструє `/voice`, оскільки -`/tts` — це вбудована команда Discord — текстова форма `/tts ...` усе одно працює. +Одна команда `/tts`. У Discord OpenClaw також реєструє `/voice`, оскільки +`/tts` є вбудованою командою Discord — текстова `/tts ...` все одно працює. ```text /tts off | on | status @@ -654,325 +654,327 @@ voice, model або speed для однієї відповіді, а також ``` -Команди потребують авторизованого відправника (діють правила allowlist/owner) і -має бути ввімкнено або `commands.text`, або нативну реєстрацію команд. +Команди потребують авторизованого відправника (застосовуються правила allowlist/власника), а також +має бути ввімкнено `commands.text` або нативну реєстрацію команд. -Примітки щодо поведінки: +Нотатки щодо поведінки: - `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. -- `/tts chat on|off|default` записує session-scoped перевизначення auto-TTS для поточного чату. +- `/tts chat on|off|default` записує перевизначення auto-TTS в межах сесії для поточного чату. - `/tts persona ` записує локальне налаштування персони; `/tts persona off` очищує його. -- `/tts latest` зчитує останню відповідь assistant із transcript поточного сеансу й один раз надсилає її як аудіо. Він зберігає лише hash цієї відповіді в записі сеансу, щоб придушити дублікати голосових надсилань. +- `/tts latest` читає останню відповідь помічника з поточного транскрипту сесії та надсилає її як аудіо один раз. Він зберігає лише хеш цієї відповіді в записі сесії, щоб пригнічувати дублікати голосових надсилань. - `/tts audio` генерує одноразову аудіовідповідь (**не** вмикає TTS). - `limit` і `summary` зберігаються в **локальних налаштуваннях**, а не в основній конфігурації. -- `/tts status` включає діагностику fallback для останньої спроби — `Fallback: -> `, `Attempts: ...` і подробиці для кожної спроби (`provider:outcome(reasonCode) latency`). -- `/status` показує активний режим TTS, а також налаштовані провайдер, модель, голос і санітизовані метадані custom endpoint, коли TTS увімкнено. +- `/tts status` включає діагностику резервного переходу для останньої спроби — `Fallback: -> `, `Attempts: ...` і деталі кожної спроби (`provider:outcome(reasonCode) latency`). +- `/status` показує активний режим TTS, а також налаштовані провайдера, модель, голос і санітизовані метадані користувацького кінцевого пункту, коли TTS увімкнено. ## Налаштування для кожного користувача -Slash-команди записують локальні перевизначення в `prefsPath`. За замовчуванням це -`~/.openclaw/settings/tts.json`; перевизначити можна через env-змінну `OPENCLAW_TTS_PREFS` +Slash-команди записують локальні перевизначення в `prefsPath`. Типове значення: +`~/.openclaw/settings/tts.json`; перевизначте його через змінну середовища `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`. -| Збережене поле | Ефект | -| -------------- | ------------------------------------------ | +| Збережене поле | Ефект | +| -------------- | ------------------------------------------------ | | `auto` | Локальне перевизначення auto-TTS (`always`, `off`, …) | -| `provider` | Локальне перевизначення основного провайдера | -| `persona` | Локальне перевизначення персони | -| `maxLength` | Поріг summary (типово `1500` символів) | -| `summarize` | Перемикач summary (типово `true`) | +| `provider` | Локальне перевизначення основного провайдера | +| `persona` | Локальне перевизначення персони | +| `maxLength` | Поріг підсумовування (типово `1500` символів) | +| `summarize` | Перемикач підсумовування (типово `true`) | -Вони перевизначають ефективну конфігурацію з `messages.tts` разом з активним -блоком `agents.list[].tts` для цього host. +Вони перевизначають ефективну конфігурацію з `messages.tts` плюс активний +блок `agents.list[].tts` для цього хоста. ## Формати виводу (фіксовані) -Доставка голосу TTS визначається можливостями каналу. Plugins каналів оголошують, -чи має TTS у стилі voice просити провайдерів про нативну ціль `voice-note`, чи -зберігати звичайний синтез `audio-file` і лише позначати сумісний вивід для -голосової доставки. +Голосова доставка TTS керується можливостями каналу. Channel plugins оголошують, +чи має голосовий TTS просити провайдерів про нативну ціль `voice-note`, чи +зберігати звичайний синтез `audio-file` і лише позначати сумісний вивід для голосової +доставки. -- **Канали з підтримкою voice-note**: відповіді у форматі voice-note віддають перевагу Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень. -- **Feishu / WhatsApp**: коли відповідь у форматі voice-note створюється як MP3/WebM/WAV/M4A - або інший імовірний аудіофайл, Plugin каналу перекодовує її в 48 кГц +- **Канали з підтримкою голосових нотаток**: відповіді голосовими нотатками надають перевагу Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). + - 48 кГц / 64 кбіт/с — добрий компроміс для голосових повідомлень. +- **Feishu / WhatsApp**: коли відповідь голосовою нотаткою створюється як MP3/WebM/WAV/M4A + або інший імовірний аудіофайл, Plugin каналу транскодує її у 48 кГц Ogg/Opus за допомогою `ffmpeg` перед надсиланням нативного голосового повідомлення. WhatsApp надсилає результат через payload Baileys `audio` з `ptt: true` і - `audio/ogg; codecs=opus`. Якщо конвертація завершується помилкою, Feishu отримує початковий - файл як вкладення; надсилання WhatsApp завершується помилкою замість публікації несумісного + `audio/ogg; codecs=opus`. Якщо конвертація не вдається, Feishu отримує оригінальний + файл як вкладення; надсилання WhatsApp завершується помилкою, а не публікує несумісний payload PTT. -- **BlueBubbles**: залишає синтез провайдера на звичайному шляху audio-file; виводи MP3 - і CAF позначаються для доставки голосових нотаток iMessage. +- **BlueBubbles**: зберігає синтез провайдера у звичайному шляху аудіофайлу; вихідні файли MP3 + і CAF позначаються для доставлення голосової нотатки iMessage. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. -- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для оголошених каналом цілей voice-note OpenClaw перекодовує MP3 MiniMax у 48 кГц Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку перекодування. -- **Xiaomi MiMo**: MP3 за замовчуванням або WAV, якщо налаштовано. Для оголошених каналом цілей voice-note OpenClaw перекодовує вивід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку перекодування. -- **Local CLI**: використовує налаштований `outputFormat`. Цілі voice-note - конвертуються в Ogg/Opus, а вивід для телефонії — у сирий 16 кГц моно PCM + - 44,1 кГц / 128 кбіт/с — стандартний баланс для чіткості мовлення. +- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для оголошених каналом цілей голосових нотаток OpenClaw транскодує MiniMax MP3 у 48 кГц Opus за допомогою `ffmpeg` перед доставленням, коли канал оголошує транскодування. +- **Xiaomi MiMo**: MP3 за замовчуванням або WAV, якщо налаштовано. Для оголошених каналом цілей голосових нотаток OpenClaw транскодує вихід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставленням, коли канал оголошує транскодування. +- **Локальний CLI**: використовує налаштований `outputFormat`. Цілі голосових нотаток + конвертуються в Ogg/Opus, а телефонний вихід конвертується в сирий 16 кГц моно PCM за допомогою `ffmpeg`. -- **Google Gemini**: Gemini API TTS повертає сирий 24 кГц PCM. OpenClaw обгортає його у WAV для аудіовкладень, перекодовує в 48 кГц Opus для цілей voice-note і повертає PCM напряму для Talk/телефонії. -- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 кГц для телефонії. -- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей voice-note і сирий `PCM` на 22050 Гц для Talk/телефонії. -- **xAI**: MP3 за замовчуванням; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетну REST-кінцеву точку TTS xAI і повертає повністю готове аудіовкладення; потоковий WebSocket TTS xAI цим шляхом провайдера не використовується. Нативний формат voice-note Opus цим шляхом не підтримується. -- **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований transport приймає `outputFormat`, але не всі формати доступні в сервісі. - - Значення формату виводу відповідають форматам виводу Microsoft Speech (зокрема Ogg/WebM Opus). - - `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні +- **Google Gemini**: Gemini API TTS повертає сирий 24 кГц PCM. OpenClaw обгортає його як WAV для аудіовкладень, транскодує його у 48 кГц Opus для цілей голосових нотаток і повертає PCM напряму для Talk/телефонії. +- **Gradium**: WAV для аудіовкладень, Opus для цілей голосових нотаток і `ulaw_8000` на 8 кГц для телефонії. +- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей голосових нотаток і сирий `PCM` на 22050 Гц для Talk/телефонії. +- **xAI**: MP3 за замовчуванням; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує batch REST TTS endpoint xAI і повертає повне аудіовкладення; streaming TTS WebSocket xAI не використовується цим шляхом провайдера. Нативний формат голосових нотаток Opus не підтримується цим шляхом. +- **Microsoft**: використовує `microsoft.outputFormat` (за замовчуванням `audio-24khz-48kbitrate-mono-mp3`). + - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні із сервісу. + - Значення формату виходу відповідають форматам виходу Microsoft Speech (зокрема Ogg/WebM Opus). + - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. - - Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. + - Якщо налаштований формат виходу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. -Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). +Формати виходу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). -## Поведінка auto-TTS +## Поведінка Auto-TTS Коли `messages.tts.auto` увімкнено, OpenClaw: - Пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - Пропускає дуже короткі відповіді (менше 10 символів). -- Узагальнює довгі відповіді, якщо summaries увімкнено, використовуючи +- Узагальнює довгі відповіді, коли узагальнення увімкнені, використовуючи `summaryModel` (або `agents.defaults.model.primary`). - Додає згенероване аудіо до відповіді. -- У режимі `mode: "final"` усе одно надсилає TTS лише як аудіо для фінальних потокових відповідей - після завершення текстового потоку; згенеровані медіадані проходять ту саму +- У `mode: "final"` усе одно надсилає audio-only TTS для streamed final replies + після завершення текстового stream; згенероване медіа проходить через ту саму нормалізацію медіа каналу, що й звичайні вкладення відповіді. -Якщо відповідь перевищує `maxLength`, а summary вимкнено (або немає API-ключа для -моделі summary), аудіо пропускається й надсилається звичайна текстова відповідь. +Якщо відповідь перевищує `maxLength`, а узагальнення вимкнене (або немає API key для +моделі узагальнення), аудіо пропускається, і надсилається звичайна текстова відповідь. ```text -Відповідь -> TTS увімкнено? - ні -> надіслати текст - так -> є медіа / MEDIA: / коротка? - так -> надіслати текст - ні -> довжина > ліміт? - ні -> TTS -> додати аудіо - так -> summary увімкнено? - ні -> надіслати текст - так -> summary -> TTS -> додати аудіо +Reply -> TTS enabled? + no -> send text + yes -> has media / MEDIA: / short? + yes -> send text + no -> length > limit? + no -> TTS -> attach audio + yes -> summary enabled? + no -> send text + yes -> summarize -> TTS -> attach audio ``` -## Формати виводу за каналом +## Формати виходу за каналом -| Ціль | Формат | -| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| Feishu / Matrix / Telegram / WhatsApp | Відповіді у форматі voice-note віддають перевагу **Opus** (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). 48 кГц / 64 кбіт/с балансує чіткість і розмір. | -| Інші канали | **MP3** (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). 44,1 кГц / 128 кбіт/с — типовий варіант для мовлення. | -| Talk / телефонія | Нативний для провайдера **PCM** (Inworld 22050 Гц, Google 24 кГц) або `ulaw_8000` від Gradium для телефонії. | + | Ціль | Формат | + | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | + | Feishu / Matrix / Telegram / WhatsApp | Відповіді голосовими нотатками надають перевагу **Opus** (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). 48 кГц / 64 кбіт/с балансує чіткість і розмір. | + | Інші канали | **MP3** (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). 44,1 кГц / 128 кбіт/с типово для мовлення. | + | Talk / телефонія | Нативний для постачальника **PCM** (Inworld 22050 Гц, Google 24 кГц) або `ulaw_8000` від Gradium для телефонії. | -Примітки для окремих провайдерів: + Примітки за постачальниками: -- **Перекодування Feishu / WhatsApp:** Коли відповідь у форматі voice-note надходить як MP3/WebM/WAV/M4A, Plugin каналу перекодовує її у 48 кГц Ogg/Opus за допомогою `ffmpeg`. WhatsApp надсилає через Baileys з `ptt: true` і `audio/ogg; codecs=opus`. Якщо конвертація завершується помилкою: Feishu повертається до вкладення початкового файла; надсилання WhatsApp завершується помилкою замість публікації несумісного payload PTT. -- **MiniMax / Xiaomi MiMo:** Типово MP3 (32 кГц для MiniMax `speech-2.8-hd`); перекодовується в 48 кГц Opus для цілей voice-note через `ffmpeg`. -- **Local CLI:** Використовує налаштований `outputFormat`. Цілі voice-note конвертуються в Ogg/Opus, а вивід для телефонії — у сирий 16 кГц моно PCM. -- **Google Gemini:** Повертає сирий 24 кГц PCM. OpenClaw обгортає його у WAV для вкладень, перекодовує в 48 кГц Opus для цілей voice-note, повертає PCM напряму для Talk/телефонії. -- **Inworld:** MP3-вкладення, нативний `OGG_OPUS` для voice-note, сирий `PCM` 22050 Гц для Talk/телефонії. -- **xAI:** MP3 за замовчуванням; `responseFormat` може бути `mp3|wav|pcm|mulaw|alaw`. Використовує пакетну кінцеву точку REST xAI — потоковий WebSocket TTS **не** використовується. Нативний формат voice-note Opus **не** підтримується. -- **Microsoft:** Використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. Якщо налаштований формат Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. + - **Транскодування Feishu / WhatsApp:** Коли відповідь голосовою нотаткою надходить як MP3/WebM/WAV/M4A, Plugin каналу транскодує її в 48 кГц Ogg/Opus за допомогою `ffmpeg`. WhatsApp надсилає через Baileys із `ptt: true` та `audio/ogg; codecs=opus`. Якщо перетворення не вдається: Feishu повертається до вкладення оригінального файлу; надсилання WhatsApp завершується помилкою замість публікації несумісного PTT-навантаження. + - **MiniMax / Xiaomi MiMo:** Типово MP3 (32 кГц для MiniMax `speech-2.8-hd`); транскодується в 48 кГц Opus для цілей голосових нотаток через `ffmpeg`. + - **Локальний CLI:** Використовує налаштований `outputFormat`. Цілі голосових нотаток перетворюються на Ogg/Opus, а телефонний вихід — на сирий моно PCM 16 кГц. + - **Google Gemini:** Повертає сирий PCM 24 кГц. OpenClaw обгортає його як WAV для вкладень, транскодує в 48 кГц Opus для цілей голосових нотаток, повертає PCM напряму для Talk/телефонії. + - **Inworld:** MP3-вкладення, нативний `OGG_OPUS` для голосових нотаток, сирий `PCM` 22050 Гц для Talk/телефонії. + - **xAI:** Типово MP3; `responseFormat` може бути `mp3|wav|pcm|mulaw|alaw`. Використовує пакетну REST-кінцеву точку xAI — потоковий WebSocket TTS **не** використовується. Нативний формат Opus для голосових нотаток **не** підтримується. + - **Microsoft:** Використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. Якщо налаштований формат Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. -Формати виводу OpenAI та ElevenLabs фіксовані для кожного каналу, як указано вище. + Формати виводу OpenAI та ElevenLabs фіксовані для кожного каналу, як зазначено вище. -## Довідник полів + ## Довідник полів - - + + - Режим auto-TTS. `inbound` надсилає аудіо лише після вхідного голосового повідомлення; `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:...]]` або блок `[[tts:text]]`. + Режим автоматичного TTS. `inbound` надсилає аудіо лише після вхідного голосового повідомлення; `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:...]]` або блок `[[tts:text]]`. - Застарілий перемикач. `openclaw doctor --fix` переносить його в `auto`. + Застарілий перемикач. `openclaw doctor --fix` переносить це в `auto`. `"all"` включає відповіді інструментів/блоків на додачу до фінальних відповідей. - Ідентифікатор speech-провайдера. Якщо не задано, OpenClaw використовує першого налаштованого провайдера в порядку auto-select реєстру. Застаріле `provider: "edge"` переписується в `"microsoft"` за допомогою `openclaw doctor --fix`. + Ідентифікатор постачальника мовлення. Якщо не задано, OpenClaw використовує першого налаштованого постачальника в порядку автоматичного вибору реєстру. Застаріле `provider: "edge"` переписується на `"microsoft"` командою `openclaw doctor --fix`. Ідентифікатор активної персони з `personas`. Нормалізується до нижнього регістру. - Стабільна мовленнєва ідентичність. Поля: `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.`. Див. [Персони](#personas). + Стабільна розмовна ідентичність. Поля: `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.`. Див. [Персони](#personas). - Дешева модель для auto-summary; типово `agents.defaults.model.primary`. Приймає `provider/model` або налаштований псевдонім моделі. + Дешева модель для автоматичного підсумку; типово `agents.defaults.model.primary`. Приймає `provider/model` або налаштований псевдонім моделі. - Дозволяє моделі виводити директиви TTS. `enabled` типово дорівнює `true`; `allowProvider` типово дорівнює `false`. + Дозволяє моделі видавати директиви TTS. `enabled` типово `true`; `allowProvider` типово `false`. - Налаштування, що належать провайдеру, з ключем за ідентифікатором speech-провайдера. Застарілі прямі блоки (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) переписуються `openclaw doctor --fix`; комітьте лише `messages.tts.providers.`. + Налаштування, що належать постачальнику, з ключами за ідентифікатором постачальника мовлення. Застарілі прямі блоки (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) переписуються командою `openclaw doctor --fix`; комітьте лише `messages.tts.providers.`. - Жорсткий ліміт символів для вхідного тексту TTS. `/tts audio` завершується помилкою, якщо його перевищено. + Жорстке обмеження кількості символів для входу TTS. `/tts audio` завершується помилкою, якщо його перевищено. Тайм-аут запиту в мілісекундах. - Перевизначає шлях до JSON локальних налаштувань (provider/limit/summary). Типово `~/.openclaw/settings/tts.json`. + Перевизначає локальний шлях JSON налаштувань (постачальник/ліміт/підсумок). Типово `~/.openclaw/settings/tts.json`. - Env: `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` або `SPEECH_KEY`. - Регіон Azure Speech (наприклад, `eastus`). Env: `AZURE_SPEECH_REGION` або `SPEECH_REGION`. - Необов’язкове перевизначення endpoint Azure Speech (псевдонім `baseUrl`). + Резервно використовує `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` або `SPEECH_KEY`. + Регіон Azure Speech (наприклад, `eastus`). Змінні середовища: `AZURE_SPEECH_REGION` або `SPEECH_REGION`. + Необов’язкове перевизначення кінцевої точки Azure Speech (псевдонім `baseUrl`). ShortName голосу Azure. Типово `en-US-JennyNeural`. Код мови SSML. Типово `en-US`. Azure `X-Microsoft-OutputFormat` для стандартного аудіо. Типово `audio-24khz-48kbitrate-mono-mp3`. - Azure `X-Microsoft-OutputFormat` для виводу voice-note. Типово `ogg-24khz-16bit-mono-opus`. + Azure `X-Microsoft-OutputFormat` для виводу голосових нотаток. Типово `ogg-24khz-16bit-mono-opus`. - Використовує як fallback `ELEVENLABS_API_KEY` або `XI_API_KEY`. + Резервно використовує `ELEVENLABS_API_KEY` або `XI_API_KEY`. Ідентифікатор моделі (наприклад, `eleven_multilingual_v2`, `eleven_v3`). Ідентифікатор голосу ElevenLabs. - `stability`, `similarityBoost`, `style` (кожне `0..1`), `useSpeakerBoost` (`true|false`), `speed` (`0.5..2.0`, `1.0` = звичайна). + `stability`, `similarityBoost`, `style` (кожен `0..1`), `useSpeakerBoost` (`true|false`), `speed` (`0.5..2.0`, `1.0` = нормально). Режим нормалізації тексту. 2-літерний ISO 639-1 (наприклад, `en`, `de`). - Ціле число `0..4294967295` для best-effort детермінованості. + Ціле число `0..4294967295` для детермінізму за принципом найкращого зусилля. Перевизначає базову URL-адресу API ElevenLabs. - Використовує як fallback `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Якщо пропущено, TTS може повторно використати `models.providers.google.apiKey` перед fallback до env. + Резервно використовує `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Якщо пропущено, TTS може повторно використовувати `models.providers.google.apiKey` перед резервним використанням змінних середовища. Модель Gemini TTS. Типово `gemini-3.1-flash-tts-preview`. - Назва вбудованого голосу Gemini. Типово `Kore`. Псевдонім: `voice`. - Запит стилю природною мовою, що додається перед озвучуваним текстом. - Необов’язкова мітка мовця, що додається перед озвучуваним текстом, коли ваш prompt використовує іменованого мовця. - Установіть `audio-profile-v1`, щоб обгорнути поля prompt активної персони в детерміновану структуру prompt Gemini TTS. - Додатковий текст prompt персони, специфічний для Google, який додається до Director's Notes шаблону. + Назва готового голосу Gemini. Типово `Kore`. Псевдонім: `voice`. + Підказка стилю природною мовою, що додається перед вимовленим текстом. + Необов’язкова мітка мовця, що додається перед вимовленим текстом, коли ваша підказка використовує названого мовця. + Установіть `audio-profile-v1`, щоб обгорнути активні поля підказки персони в детерміновану структуру підказки Gemini TTS. + Додатковий текст підказки персони, специфічний для Google, що додається до Director's Notes шаблону. Приймається лише `https://generativelanguage.googleapis.com`. - Env: `GRADIUM_API_KEY`. - Типово `https://api.gradium.ai`. - Типово Emma (`YTpq7expH9539ERJ`). + Змінна середовища: `GRADIUM_API_KEY`. + За замовчуванням `https://api.gradium.ai`. + За замовчуванням Emma (`YTpq7expH9539ERJ`). - Env: `INWORLD_API_KEY`. - Типово `https://api.inworld.ai`. - Типово `inworld-tts-1.5-max`. Також: `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`. - Типово `Sarah`. + Змінна середовища: `INWORLD_API_KEY`. + За замовчуванням `https://api.inworld.ai`. + За замовчуванням `inworld-tts-1.5-max`. Також: `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`. + За замовчуванням `Sarah`. Температура семплювання `0..2`. Локальний виконуваний файл або рядок команди для CLI TTS. - Аргументи команди. Підтримує placeholders `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}`, `{{OutputBase}}`. - Очікуваний формат виводу CLI. Типово `mp3` для аудіовкладень. - Тайм-аут команди в мілісекундах. Типово `120000`. + Аргументи команди. Підтримує заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}`, `{{OutputBase}}`. + Очікуваний формат виводу CLI. За замовчуванням `mp3` для аудіовкладень. + Тайм-аут команди в мілісекундах. За замовчуванням `120000`. Необов’язковий робочий каталог команди. Необов’язкові перевизначення середовища для команди. - - Дозволяє використання Microsoft speech. - Назва neural-голосу Microsoft (наприклад, `en-US-MichelleNeural`). + + Дозволити використання мовлення Microsoft. + Назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). Код мови (наприклад, `en-US`). - Формат виводу Microsoft. Типово `audio-24khz-48kbitrate-mono-mp3`. Не всі формати підтримуються вбудованим transport на базі Edge. - Рядки відсотків (наприклад, `+10%`, `-5%`). - Записує JSON-субтитри поруч з аудіофайлом. - URL-адреса proxy для запитів speech Microsoft. + Формат виводу Microsoft. За замовчуванням `audio-24khz-48kbitrate-mono-mp3`. Не всі формати підтримуються вбудованим транспортом на основі Edge. + Відсоткові рядки (наприклад, `+10%`, `-5%`). + Записувати субтитри JSON поряд з аудіофайлом. + URL проксі для запитів мовлення Microsoft. Перевизначення тайм-ауту запиту (мс). - Застарілий псевдонім. Запустіть `openclaw doctor --fix`, щоб переписати збережену конфігурацію в `providers.microsoft`. + Застарілий псевдонім. Запустіть `openclaw doctor --fix`, щоб переписати збережену конфігурацію на `providers.microsoft`. - Використовує як fallback `MINIMAX_API_KEY`. Auth Token Plan через `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY` або `MINIMAX_CODING_API_KEY`. - Типово `https://api.minimax.io`. Env: `MINIMAX_API_HOST`. - Типово `speech-2.8-hd`. Env: `MINIMAX_TTS_MODEL`. - Типово `English_expressive_narrator`. Env: `MINIMAX_TTS_VOICE_ID`. - `0.5..2.0`. Типово `1.0`. - `(0, 10]`. Типово `1.0`. - Ціле число `-12..12`. Типово `0`. Дробові значення відкидаються перед запитом. + Як резерв використовує `MINIMAX_API_KEY`. Автентифікація Token Plan через `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY` або `MINIMAX_CODING_API_KEY`. + За замовчуванням `https://api.minimax.io`. Змінна середовища: `MINIMAX_API_HOST`. + За замовчуванням `speech-2.8-hd`. Змінна середовища: `MINIMAX_TTS_MODEL`. + За замовчуванням `English_expressive_narrator`. Змінна середовища: `MINIMAX_TTS_VOICE_ID`. + `0.5..2.0`. За замовчуванням `1.0`. + `(0, 10]`. За замовчуванням `1.0`. + Ціле число `-12..12`. За замовчуванням `0`. Дробові значення обрізаються перед запитом. - Використовує як fallback `OPENAI_API_KEY`. + Як резерв використовує `OPENAI_API_KEY`. Ідентифікатор моделі OpenAI TTS (наприклад, `gpt-4o-mini-tts`). Назва голосу (наприклад, `alloy`, `cedar`). - Явне поле OpenAI `instructions`. Коли встановлено, поля prompt персони **не** зіставляються автоматично. + Явне поле OpenAI `instructions`. Коли воно задане, поля промпту персони **не** зіставляються автоматично. + Додаткові поля JSON, що об’єднуються з тілами запитів `/audio/speech` після згенерованих полів OpenAI TTS. Використовуйте це для сумісних з OpenAI кінцевих точок, як-от Kokoro, яким потрібні специфічні для провайдера ключі на кшталт `lang`; небезпечні ключі прототипу ігноруються. - Перевизначає endpoint OpenAI TTS. Порядок визначення: config → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. Нестандартні значення розглядаються як OpenAI-сумісні endpoints TTS, тому приймаються власні назви моделей і голосів. + Перевизначає кінцеву точку OpenAI TTS. Порядок розв’язання: конфігурація → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. Значення, відмінні від стандартного, розглядаються як сумісні з OpenAI кінцеві точки TTS, тому приймаються власні назви моделей і голосів. - Env: `OPENROUTER_API_KEY`. Може повторно використовувати `models.providers.openrouter.apiKey`. - Типово `https://openrouter.ai/api/v1`. Застаріле `https://openrouter.ai/v1` нормалізується. - Типово `hexgrad/kokoro-82m`. Псевдонім: `modelId`. - Типово `af_alloy`. Псевдонім: `voiceId`. - Типово `mp3`. - Нативне для провайдера перевизначення швидкості. + Змінна середовища: `OPENROUTER_API_KEY`. Може повторно використовувати `models.providers.openrouter.apiKey`. + За замовчуванням `https://openrouter.ai/api/v1`. Застарілий `https://openrouter.ai/v1` нормалізується. + За замовчуванням `hexgrad/kokoro-82m`. Псевдонім: `modelId`. + За замовчуванням `af_alloy`. Псевдонім: `voiceId`. + За замовчуванням `mp3`. + Перевизначення швидкості у форматі провайдера. - Env: `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY`. - Типово `seed-tts-1.0`. Env: `VOLCENGINE_TTS_RESOURCE_ID`. Використовуйте `seed-tts-2.0`, коли ваш проєкт має entitlement TTS 2.0. - Заголовок app key. Типово `aGjiRDfUWi`. Env: `VOLCENGINE_TTS_APP_KEY`. - Перевизначає HTTP endpoint TTS Seed Speech. Env: `VOLCENGINE_TTS_BASE_URL`. - Тип голосу. Типово `en_female_anna_mars_bigtts`. Env: `VOLCENGINE_TTS_VOICE`. - Нативне для провайдера співвідношення швидкості. - Нативний для провайдера тег emotion. - Застарілі поля Volcengine Speech Console. Env: `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (типово `volcano_tts`). + Змінна середовища: `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY`. + За замовчуванням `seed-tts-1.0`. Змінна середовища: `VOLCENGINE_TTS_RESOURCE_ID`. Використовуйте `seed-tts-2.0`, коли ваш проєкт має право на TTS 2.0. + Заголовок ключа застосунку. За замовчуванням `aGjiRDfUWi`. Змінна середовища: `VOLCENGINE_TTS_APP_KEY`. + Перевизначає HTTP-кінцеву точку Seed Speech TTS. Змінна середовища: `VOLCENGINE_TTS_BASE_URL`. + Тип голосу. За замовчуванням `en_female_anna_mars_bigtts`. Змінна середовища: `VOLCENGINE_TTS_VOICE`. + Коефіцієнт швидкості у форматі провайдера. + Тег емоції у форматі провайдера. + Застарілі поля Volcengine Speech Console. Змінні середовища: `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (за замовчуванням `volcano_tts`). - Env: `XAI_API_KEY`. - Типово `https://api.x.ai/v1`. Env: `XAI_BASE_URL`. - Типово `eve`. Live-голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`. - Код мови BCP-47 або `auto`. Типово `en`. - Типово `mp3`. - Нативне для провайдера перевизначення швидкості. + Змінна середовища: `XAI_API_KEY`. + За замовчуванням `https://api.x.ai/v1`. Змінна середовища: `XAI_BASE_URL`. + За замовчуванням `eve`. Доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`. + Код мови BCP-47 або `auto`. За замовчуванням `en`. + За замовчуванням `mp3`. + Перевизначення швидкості у форматі провайдера. - Env: `XIAOMI_API_KEY`. - Типово `https://api.xiaomimimo.com/v1`. Env: `XIAOMI_BASE_URL`. - Типово `mimo-v2.5-tts`. Env: `XIAOMI_TTS_MODEL`. Також підтримує `mimo-v2-tts`. - Типово `mimo_default`. Env: `XIAOMI_TTS_VOICE`. - Типово `mp3`. Env: `XIAOMI_TTS_FORMAT`. - Необов’язкова інструкція стилю природною мовою, яка надсилається як повідомлення користувача; не озвучується. + Змінна середовища: `XIAOMI_API_KEY`. + За замовчуванням `https://api.xiaomimimo.com/v1`. Змінна середовища: `XIAOMI_BASE_URL`. + За замовчуванням `mimo-v2.5-tts`. Змінна середовища: `XIAOMI_TTS_MODEL`. Також підтримує `mimo-v2-tts`. + За замовчуванням `mimo_default`. Змінна середовища: `XIAOMI_TTS_VOICE`. + За замовчуванням `mp3`. Змінна середовища: `XIAOMI_TTS_FORMAT`. + Необов’язкова інструкція стилю природною мовою, що надсилається як повідомлення користувача; не озвучується. -## Інструмент agent +## Інструмент агента Інструмент `tts` перетворює текст на мовлення й повертає аудіовкладення для -доставки у відповіді. У Feishu, Matrix, Telegram і WhatsApp аудіо +доставки відповіді. У Feishu, Matrix, Telegram і WhatsApp аудіо доставляється як голосове повідомлення, а не як файлове вкладення. Feishu і -WhatsApp можуть перекодовувати вивід TTS, що не є Opus, цим шляхом, коли доступний `ffmpeg`. +WhatsApp можуть перекодовувати вивід TTS не у форматі Opus на цьому шляху, коли `ffmpeg` +доступний. WhatsApp надсилає аудіо через Baileys як голосову нотатку PTT (`audio` з `ptt: true`) і надсилає видимий текст **окремо** від аудіо PTT, оскільки -клієнти не завжди коректно відображають підписи до голосових нотаток. +клієнти не завжди стабільно відображають підписи до голосових нотаток. Інструмент приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це -тайм-аут запиту до провайдера для кожного виклику в мілісекундах. +тайм-аут запиту провайдера для кожного виклику в мілісекундах. ## Gateway RPC | Метод | Призначення | | ----------------- | ---------------------------------------- | -| `tts.status` | Зчитати поточний стан TTS і останню спробу. | -| `tts.enable` | Установити локальне налаштування auto на `always`. | -| `tts.disable` | Установити локальне налаштування auto на `off`. | +| `tts.status` | Читати поточний стан TTS і останню спробу. | +| `tts.enable` | Установити локальну автоматичну перевагу на `always`. | +| `tts.disable` | Установити локальну автоматичну перевагу на `off`. | | `tts.convert` | Одноразове перетворення текст → аудіо. | -| `tts.setProvider` | Установити локальне налаштування провайдера. | -| `tts.setPersona` | Установити локальне налаштування персони. | -| `tts.providers` | Перелічити налаштованих провайдерів і стан. | +| `tts.setProvider` | Установити локальну перевагу провайдера. | +| `tts.setPersona` | Установити локальну перевагу персони. | +| `tts.providers` | Перелічити налаштованих провайдерів і статус. | ## Посилання на сервіси -- [Посібник OpenAI з text-to-speech](https://platform.openai.com/docs/guides/text-to-speech) -- [Довідник API OpenAI Audio](https://platform.openai.com/docs/api-reference/audio) -- [Azure Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) +- [Посібник OpenAI з перетворення тексту на мовлення](https://platform.openai.com/docs/guides/text-to-speech) +- [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) +- [Azure Speech REST для перетворення тексту на мовлення](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) - [Провайдер Azure Speech](/uk/providers/azure-speech) - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) @@ -983,7 +985,7 @@ WhatsApp надсилає аудіо через Baileys як голосову н - [Синтез мовлення Xiaomi MiMo](/uk/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -- [xAI text to speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) +- [xAI перетворення тексту на мовлення](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## Пов’язане @@ -991,4 +993,4 @@ WhatsApp надсилає аудіо через Baileys як голосову н - [Генерація музики](/uk/tools/music-generation) - [Генерація відео](/uk/tools/video-generation) - [Slash-команди](/uk/tools/slash-commands) -- [Plugin Voice call](/uk/plugins/voice-call) +- [Plugin голосових викликів](/uk/plugins/voice-call)