From acdc2066c2a3e4a4d394fe00168571dc6a7153b7 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 15:02:57 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/architecture-internals.md | 826 +++++++++++----------- 1 file changed, 415 insertions(+), 411 deletions(-) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index ee3ca15be..355287190 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,26 +1,26 @@ --- read_when: - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - - Налагодження порядку завантаження плагінів або стану реєстру + - Налагодження порядку завантаження Plugin або стану реєстру - Додавання нової можливості Plugin або Plugin рушія контексту -summary: 'Внутрішні механізми архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' -title: Внутрішня архітектура Plugin +summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' +title: Внутрішні механізми архітектури Plugin x-i18n: - generated_at: "2026-05-01T22:48:18Z" + generated_at: "2026-05-02T14:59:49Z" model: gpt-5.5 provider: openai - source_hash: 2de741c4b496c7c3dd31dafebf39c4b9a32c5edd71bdd201c14037d9de31718f + source_hash: fec593518e51f68ce617d5bc4e55cede2188e9247f863364a9ea956e50ca2675 source_path: plugins/architecture-internals.md workflow: 16 --- -Для публічної моделі можливостей, форм Plugin і контрактів володіння/виконання див. [архітектуру Plugin](/uk/plugins/architecture). Ця сторінка є довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, runtime-хуків, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. +Для публічної моделі можливостей, форм Plugin і контрактів володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка є довідником щодо внутрішніх механізмів: конвеєра завантаження, реєстру, runtime-хуків, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. виявляє корені кандидатів Plugin +1. виявляє корені Plugin-кандидатів 2. читає нативні або сумісні маніфести бандлів і метадані пакетів 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, @@ -29,102 +29,108 @@ x-i18n: 6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; сторонній локальний вихідний TypeScript використовує аварійний fallback Jiti 7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin -8. надає реєстр командам і runtime-поверхням +8. відкриває реєстр для команд/runtime-поверхонь -`activate` — це застарілий псевдонім для `register`: завантажувач визначає наявний варіант (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що доступне (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`. -Запобіжні перевірки виконуються **до** runtime-виконання. Кандидатів блокують, -коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім -користувачам або володіння шляхом виглядає підозрілим для не вбудованих Plugin. +Запобіжні перевірки виконуються **до** runtime-виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім користувачам або +володіння шляхом виглядає підозріло для невбудованих Plugin. ### Поведінка з пріоритетом маніфесту Маніфест є джерелом істини для площини керування. OpenClaw використовує його, щоб: - ідентифікувати Plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості бандла +- виявляти оголошені канали/skills/схему конфігурації або можливості бандла - перевіряти `plugins.entries..config` - доповнювати мітки/заповнювачі Control UI - показувати метадані встановлення/каталогу - зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin Для нативних Plugin runtime-модуль є частиною площини даних. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдерів. +фактичну поведінку, як-от хуки, інструменти, команди або provider-потоки. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування. -Вони є лише метаданими-дескрипторами для планування активації та виявлення налаштування; +Необов’язкові блоки маніфесту `activation` і `setup` залишаються на площині керування. +Це лише метадані-дескриптори для планування активації та виявлення налаштування; вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`. -Перші live-споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, +Перші споживачі live-активації тепер використовують підказки маніфесту щодо команд, каналів і providers, щоб звузити завантаження Plugin перед ширшою матеріалізацією реєстру: - завантаження CLI звужується до Plugin, які володіють запитаною основною командою - налаштування каналу/розв’язання Plugin звужується до Plugin, які володіють запитаним id каналу -- явне налаштування/розв’язання runtime провайдера звужується до Plugin, які володіють - запитаним id провайдера -- планування запуску Gateway використовує `activation.onStartup` для явних - імпортів під час запуску та відмов від запуску; Plugin без метаданих запуску завантажуються лише +- явне налаштування provider/розв’язання runtime звужується до Plugin, які володіють запитаним + id provider +- планування запуску Gateway використовує `activation.onStartup` для явних startup-імпортів + і відмов від запуску; Plugin без startup-метаданих завантажуються лише через вужчі тригери активації -Планувальник активації надає як API лише з ids для наявних викликачів, так і -API плану для нової діагностики. Записи плану повідомляють, чому було вибрано Plugin, -відокремлюючи явні підказки планувальника `activation.*` від fallback володіння маніфестом, +Runtime-попередні завантаження під час запиту, які просять широкий scope `all`, усе ще виводять +явний ефективний набір id Plugin з конфігурації, планування запуску, налаштованих +каналів, слотів і правил автоввімкнення. Якщо цей виведений набір порожній, OpenClaw +завантажує порожній runtime-реєстр замість розширення до кожного доступного для виявлення +Plugin. + +Планувальник активації відкриває як API лише з ids для наявних викликачів, так і +API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано, +відокремлюючи явні підказки планувальника `activation.*` від fallback-володіння маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. Такий поділ причин є межею сумісності: +`contracts.tools` і хуки. Це розділення причин є межею сумісності: наявні метадані Plugin продовжують працювати, а новий код може виявляти широкі підказки або fallback-поведінку без зміни семантики runtime-завантаження. Виявлення налаштування тепер надає перевагу id, якими володіють дескриптори, як-от `setup.providers` і -`setup.cliBackends`, щоб звузити Plugin-кандидати перед fallback до -`setup-api` для Plugin, яким досі потрібні runtime-хуки під час налаштування. Списки -налаштування провайдерів використовують `providerAuthChoices` маніфесту, варіанти налаштування, -похідні від дескрипторів, і метадані каталогу встановлення без завантаження runtime провайдера. Явне -`setup.requiresRuntime: false` є дескрипторним-only відсіканням; пропущене -`requiresRuntime` зберігає застарілий fallback `setup-api` для сумісності. Якщо більш -ніж один виявлений Plugin заявляє той самий нормалізований id провайдера налаштування або CLI -backend, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на -порядок виявлення. Коли runtime налаштування все ж виконується, діагностика реєстру повідомляє -про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або CLI -backends, зареєстрованими через setup-api, не блокуючи застарілі Plugin. +`setup.cliBackends`, щоб звузити Plugin-кандидати, перш ніж fallback-перехід до +`setup-api` для Plugin, яким усе ще потрібні runtime-хуки під час налаштування. Списки +налаштування provider використовують маніфестні `providerAuthChoices`, виведені з дескрипторів варіанти +налаштування та метадані інсталяційного каталогу без завантаження runtime provider. Явне +`setup.requiresRuntime: false` є descriptor-only межею; пропущене +`requiresRuntime` зберігає застарілий fallback до setup-api для сумісності. Якщо більше +ніж один виявлений Plugin заявляє той самий нормалізований id setup provider або CLI +backend, пошук налаштування відхиляє неоднозначного власника замість покладання на +порядок виявлення. Коли setup runtime виконується, діагностика реєстру повідомляє +про розбіжності між `setup.providers` / `setup.cliBackends` і providers або CLI +backends, зареєстрованими setup-api, без блокування застарілих Plugin. ### Межа кешу Plugin OpenClaw не кешує результати виявлення Plugin або прямі дані реєстру маніфестів -за часовими вікнами wall-clock. Встановлення, редагування маніфестів і зміни шляхів завантаження -мають ставати видимими під час наступного явного читання метаданих або перебудови знімка. -Парсер файлів маніфестів може тримати обмежений кеш файлових сигнатур із ключем за -відкритим шляхом маніфесту, inode, розміром і часовими мітками; цей кеш лише уникає -повторного парсингу незмінених байтів і не має кешувати відповіді щодо виявлення, реєстру, власника або -політики. +за часовими вікнами настінного годинника. Встановлення, редагування маніфестів і зміни load-path +мають ставати видимими під час наступного явного читання метаданих або перебудови snapshot. +Парсер файлу маніфесту може зберігати обмежений кеш сигнатур файлів, прив’язаний до +відкритого шляху маніфесту, inode, розміру й часових міток; цей кеш лише уникає +повторного парсингу незмінених байтів і не повинен кешувати відповіді щодо виявлення, +реєстру, власника або політики. Безпечний швидкий шлях метаданих — це явне володіння об’єктом, а не прихований кеш. -Гарячі шляхи запуску Gateway мають передавати поточний `PluginMetadataSnapshot`, -похідний `PluginLookUpTable` або явний реєстр маніфестів через ланцюжок викликів. -Перевірка конфігурації, автозапуск, bootstrap Plugin і вибір провайдера +Гарячі шляхи запуску Gateway мають передавати поточний `PluginMetadataSnapshot`, виведену +`PluginLookUpTable` або явний реєстр маніфестів через ланцюжок викликів. +Перевірка конфігурації, startup auto-enable, bootstrap Plugin і вибір provider можуть повторно використовувати ці об’єкти, доки вони представляють поточну конфігурацію та -інвентар Plugin. Пошук налаштування досі реконструює метадані маніфестів на вимогу, -якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; тримайте це -як fallback холодного шляху замість додавання прихованих кешів пошуку. Коли вхідні дані -змінюються, перебудовуйте й замінюйте знімок замість того, щоб мутувати його або зберігати -історичні копії. -Представлення активного реєстру Plugin і допоміжні засоби bootstrap вбудованих каналів -мають переобчислюватися з поточного реєстру/кореня. Короткоживучі мапи прийнятні -в межах одного виклику для усунення дублювання роботи або захисту від повторного входу; вони не мають ставати процесними -кешами метаданих. +інвентар Plugin. Пошук налаштування все ще реконструює метадані маніфесту на вимогу, +якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; зберігайте це +як fallback холодного шляху замість додавання прихованих кешів lookup. Коли вхідні дані +змінюються, перебудовуйте й замінюйте snapshot замість його мутації або збереження +історичних копій. +Подання над активним реєстром Plugin і helpers bootstrap для вбудованих каналів +мають переобчислюватися з поточного реєстру/кореня. Короткоживучі мапи допустимі +всередині одного виклику для дедуплікації роботи або захисту від повторного входу; вони не повинні ставати process +metadata caches. Для завантаження Plugin постійний шар кешу — це runtime-завантаження. Він може повторно використовувати -стан завантажувача, коли код або встановлені артефакти фактично завантажені, як-от: +стан завантажувача, коли код або встановлені артефакти справді завантажуються, як-от: - `PluginLoaderCacheState` і сумісні активні runtime-реєстри -- кеші jiti/модулів і кеші завантажувача публічної поверхні, що використовуються, щоб уникнути імпорту - тієї самої runtime-поверхні повторно -- кеші файлової системи для встановлених артефактів Plugin -- короткоживучі мапи на виклик для нормалізації шляхів або розв’язання дублікатів +- кеші jiti/module і кеші завантажувача public-surface, що використовуються, щоб уникати повторного імпорту + тієї самої runtime-поверхні +- файлові кеші для встановлених артефактів Plugin +- короткоживучі per-call мапи для нормалізації шляхів або розв’язання дублікатів -Ці кеші є деталями реалізації площини даних. Вони не мають відповідати -на запитання площини керування, як-от "якому Plugin належить цей провайдер?", якщо викликач +Ці кеші є деталями реалізації площини даних. Вони не повинні відповідати на +питання площини керування, як-от "який Plugin володіє цим provider?", якщо викликач навмисно не попросив runtime-завантаження. Не додавайте постійні або wall-clock кеші для: @@ -132,18 +138,17 @@ OpenClaw не кешує результати виявлення Plugin або - результатів виявлення - прямих реєстрів маніфестів - реєстрів маніфестів, реконструйованих зі встановленого індексу Plugin -- пошуку власника провайдера, пригнічення моделей, політики провайдера або метаданих - публічних артефактів -- будь-якої іншої відповіді, похідної від маніфесту, де змінений маніфест, встановлений індекс - або шлях завантаження має бути видимим під час наступного читання метаданих +- lookup власника provider, приглушення моделей, політики provider або метаданих public-artifact +- будь-якої іншої відповіді, виведеної з маніфесту, де змінений маніфест, встановлений індекс + або load path має бути видимим під час наступного читання метаданих -Викликачі, які перебудовують метадані маніфестів зі збереженого встановленого індексу Plugin, -реконструюють цей реєстр на вимогу. Встановлений індекс є довговічним -станом площини джерела; це не прихований внутрішньопроцесний кеш метаданих. +Викликачі, які перебудовують метадані маніфесту зі збереженого встановленого індексу Plugin, +реконструюють цей реєстр на вимогу. Встановлений індекс є довготривалим +станом source-plane; це не прихований in-process кеш метаданих. ## Модель реєстру -Завантажені Plugin не мутують напряму випадкові глобальні об’єкти ядра. Вони реєструються в +Завантажені Plugin не мутують напряму випадкові core globals. Вони реєструються в центральному реєстрі Plugin. Реєстр відстежує: @@ -152,28 +157,28 @@ OpenClaw не кешує результати виявлення Plugin або - інструменти - застарілі хуки та типізовані хуки - канали -- провайдерів -- обробники Gateway RPC +- providers +- RPC-обробники Gateway - HTTP-маршрути - реєстратори CLI - фонові сервіси - команди, якими володіють Plugin -Потім функції ядра читають із цього реєстру замість того, щоб напряму звертатися до модулів Plugin. +Потім core-функції читають із цього реєстру замість прямої взаємодії з модулями Plugin. Це зберігає завантаження односпрямованим: - модуль Plugin -> реєстрація в реєстрі -- runtime ядра -> споживання реєстру +- core runtime -> споживання реєстру -Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна лише -одна точка інтеграції: "читати реєстр", а не "обробляти кожен модуль Plugin окремо". +Це розділення важливе для підтримуваності. Воно означає, що більшості core-поверхонь потрібна лише +одна точка інтеграції: "прочитати реєстр", а не "спеціально обробляти кожен модуль Plugin". -## Callback-и прив’язки розмови +## Callback-и прив’язування розмови -Plugin, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. +Plugin, які прив’язують розмову, можуть реагувати, коли approval розв’язано. Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит -на прив’язку схвалено або відхилено: +на bind схвалено або відхилено: ```ts export default { @@ -193,117 +198,117 @@ export default { }; ``` -Поля payload callback: +Поля payload callback-а: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` - `binding`: розв’язана прив’язка для схвалених запитів -- `request`: початковий підсумок запиту, підказка від’єднання, id відправника та +- `request`: початковий підсумок запиту, підказка detach, id відправника та метадані розмови -Цей callback призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати -розмову, і виконується після завершення обробки схвалення ядром. +Цей callback є лише сповіщенням. Він не змінює, кому дозволено прив’язувати +розмову, і виконується після завершення core-обробки approval. -## Runtime-хуки провайдера +## Runtime-хуки provider Provider Plugin мають три шари: -- **Метадані маніфесту** для дешевого pre-runtime пошуку: - `setup.providers[].envVars`, застаріле сумісне `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого pre-runtime lookup: + `setup.providers[].envVars`, застарілий compatibility `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. -- **Хуки під час конфігурації**: `catalog` (застаріле `discovery`) плюс +- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють автентифікацію, розв’язання моделей, - обгортання потоків, рівні мислення, політику replay і endpoints використання. Див. - повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). +- **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють auth, розв’язання моделей, + обгортання stream, рівні thinking, replay policy і usage endpoints. Повний список див. + у розділі [Порядок хуків і використання](#hook-order-and-usage). -OpenClaw досі володіє загальним циклом агента, failover, обробкою transcript і -політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера -поведінки без потреби в повністю власному транспорті інференсу. +OpenClaw усе ще володіє загальним agent loop, failover, обробкою transcript і +tool policy. Ці хуки є поверхнею extension для provider-specific +поведінки без потреби в повністю кастомному inference transport. -Використовуйте `setup.providers[].envVars` маніфесту, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без -завантаження runtime Plugin. Застаріле `providerAuthEnvVars` досі читається -адаптером сумісності протягом вікна депрекації, а не вбудовані Plugin, -які його використовують, отримують діагностику маніфесту. Використовуйте -`providerAuthAliases` маніфесту, коли один id провайдера має повторно використовувати env vars, -auth profiles, auth із конфігурації та варіант onboarding для API-ключа іншого id провайдера. -Використовуйте `providerAuthChoices` маніфесту, коли CLI-поверхні onboarding/auth-choice мають знати -id варіанта провайдера, мітки груп і просте auth-підключення одним прапорцем без -завантаження runtime провайдера. Зберігайте runtime -`envVars` провайдера для підказок, орієнтованих на оператора, як-от мітки onboarding або OAuth +Використовуйте маніфестний `setup.providers[].envVars`, коли provider має env-based +облікові дані, які generic auth/status/model-picker шляхи мають бачити без +завантаження runtime Plugin. Застарілий `providerAuthEnvVars` усе ще читається +compatibility adapter протягом deprecation window, а невбудовані Plugin, +які його використовують, отримують діагностику маніфесту. Використовуйте маніфестний `providerAuthAliases`, +коли один id provider має повторно використовувати env vars, auth profiles, +config-backed auth і вибір onboarding з API key іншого id provider. Використовуйте маніфестний +`providerAuthChoices`, коли onboarding/auth-choice CLI surfaces мають знати +choice id provider, group labels і просте one-flag auth wiring без +завантаження runtime provider. Зберігайте runtime +`envVars` provider для operator-facing підказок, як-от onboarding labels або OAuth client-id/client-secret setup vars. -Використовуйте `channelEnvVars` маніфесту, коли канал має auth або налаштування на основі env, які -загальний shell-env fallback, перевірки config/status або prompts налаштування мають бачити -без завантаження runtime каналу. +Використовуйте маніфестний `channelEnvVars`, коли канал має env-driven auth або setup, які +generic shell-env fallback, config/status checks або setup prompts мають бачити +без завантаження channel runtime. -### Порядок і використання хуків +### Порядок хуків і використання -Для model/provider Plugin OpenClaw викликає хуки приблизно в такому порядку. -Стовпець "Коли використовувати" є коротким посібником для ухвалення рішення. -Compatibility-only поля провайдера, які OpenClaw більше не викликає, як-от +Для Plugin моделей/provider OpenClaw викликає хуки приблизно в такому порядку. +Стовпець "Коли використовувати" — це короткий посібник для ухвалення рішення. +Compatibility-only поля provider, які OpenClaw більше не викликає, як-от `ProviderPlugin.capabilities` і `suppressBuiltInModel`, навмисно не -перелічено тут. +перелічені тут. -| # | Хук | Що робить | Коли використовувати | -| --- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або стандартними значеннями базової URL | -| 2 | `applyConfigDefaults` | Застосовує глобальні стандартні значення конфігурації, якими володіє провайдер, під час матеріалізації конфігурації | Стандартні значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спершу пробує звичайний шлях реєстру/каталогу | _(не хук Plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми ідентифікаторів моделей перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розв’язанням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдерів перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдерів у тому самому транспортному сімействі | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням runtime/провайдера | Провайдер потребує очищення конфігурації, яке має жити з Plugin; вбудовані помічники сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи нативного streaming-usage до провайдерів конфігурації | Провайдер потребує виправлень метаданих нативного streaming usage, керованих endpoint | -| 7 | `resolveConfigApiKey` | Розв’язує автентифікацію env-marker для провайдерів конфігурації перед завантаженням автентифікації runtime | Провайдер має власне розв’язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований resolver AWS env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/самостійно розміщену або підкріплену конфігурацією автентифікацію без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, якими володіє провайдер; стандартне `persistence` — `runtime-only` для облікових даних, якими володіє CLI/застосунок | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh-токенів; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Понижує збережені синтетичні заповнювачі профілю після автентифікації, підкріпленої env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати пріоритет | -| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, якими володіє провайдер і яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream-ідентифікатори моделей | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдер потребує мережевих метаданих перед розв’язанням невідомих ідентифікаторів | -| 13 | `normalizeResolvedModel` | Фінальний перезапис перед тим, як вбудований runner використає розв’язану модель | Провайдер потребує транспортних перезаписів, але все ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах без перебирання контролю над провайдером | -| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдер потребує очищення схем транспортного сімейства | -| 16 | `inspectToolSchemas` | Показує діагностику схем, якою володіє провайдер, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | -| 17 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт reasoning-output | Провайдер потребує тегованого reasoning/final output замість нативних полів | -| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій stream | Провайдер потребує стандартних параметрів запиту або очищення параметрів для окремого провайдера | -| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream користувацьким транспортом | Провайдер потребує користувацького wire-протоколу, а не лише обгортки | -| 20 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Провайдер потребує compat-обгорток заголовків/тіла/моделі запиту без користувацького транспорту | -| 21 | `resolveTransportTurnState` | Прикріплює нативні транспортні заголовки або метадані для окремого turn | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність turn | -| 22 | `resolveWebSocketSessionPolicy` | Прикріплює нативні WebSocket-заголовки або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або fallback-політику | -| 23 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає runtime-рядком `apiKey` | Провайдер зберігає додаткові метадані автентифікації та потребує користувацької форми runtime-токена | -| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких endpoint оновлення або політики помилки оновлення | Провайдер не вписується у спільні оновлювачі `pi-ai` | -| 25 | `buildAuthDoctorHint` | Підказка для відновлення, додана після збою оновлення OAuth | Провайдер потребує власних порад з виправлення автентифікації після збою оновлення | -| 26 | `matchesContextOverflowError` | Власний для провайдера matcher переповнення context-window | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б | -| 27 | `classifyFailoverReason` | Власна для провайдера класифікація причини failover | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | -| 28 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдер потребує специфічного для proxy обмеження cache TTL | -| 29 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутньої автентифікації | Провайдер потребує специфічної для провайдера підказки відновлення відсутньої автентифікації | -| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після discovery | Провайдер потребує синтетичних forward-compat рядків у `models list` і picker-ах | -| 31 | `resolveThinkingProfile` | Набір рівнів `/think` для моделі, відображувані мітки та стандартне значення | Провайдер надає користувацьку шкалу thinking або бінарну мітку для вибраних моделей | -| 32 | `isBinaryThinking` | Compat-хук перемикача reasoning увімк./вимк. | Провайдер надає лише бінарне thinking увімк./вимк. | -| 33 | `supportsXHighThinking` | Compat-хук підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | -| 34 | `resolveDefaultThinkingLevel` | Compat-хук стандартного рівня `/think` | Провайдер володіє стандартною політикою `/think` для сімейства моделей | -| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей | -| 36 | `prepareRuntimeAuth` | Обмін налаштованих облікових даних на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдер потребує обміну токена або короткоживучих облікових даних запиту | -| 37 | `resolveUsageAuth` | Визначити облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання | -| 38 | `fetchUsageSnapshot` | Отримати й нормалізувати специфічні для провайдера знімки використання/квоти після визначення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження | -| 39 | `createEmbeddingProvider` | Побудувати належний провайдеру адаптер векторних представлень для пам’яті/пошуку | Поведінка векторних представлень пам’яті належить Plugin провайдера | -| 40 | `buildReplayPolicy` | Повернути політику повторного відтворення, що керує обробкою транскрипта для провайдера | Провайдеру потрібна власна політика транскрипта (наприклад, вилучення блоків мислення) | -| 41 | `sanitizeReplayHistory` | Переписати історію повторного відтворення після загального очищення транскрипта | Провайдеру потрібні специфічні для провайдера переписування повторного відтворення поза спільними допоміжними засобами Compaction | -| 42 | `validateReplayTurns` | Остаточна перевірка або переформування ходів повторного відтворення перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | -| 43 | `onModelSelected` | Виконати належні провайдеру побічні ефекти після вибору | Провайдеру потрібна телеметрія або належний провайдеру стан, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями базової URL-адреси | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, середовища або семантики родини моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не хук plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розпізнаванням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` родини провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в тій самій родині транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розпізнаванням runtime/провайдера | Провайдер потребує очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби родини Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування нативного використання потокового передавання до провайдерів конфігурації | Провайдер потребує виправлень метаданих нативного використання потокового передавання, керованих endpoint | +| 7 | `resolveConfigApiKey` | Розпізнає автентифікацію через env-маркер для провайдерів конфігурації перед завантаженням runtime-автентифікації | Провайдер має власне для провайдера розпізнавання API-ключа через env-маркер; `amazon-bedrock` також має тут вбудований розпізнавач AWS env-маркера | +| 8 | `resolveSyntheticAuth` | Надає локальну/самостійно розгорнуту або конфігураційно підкріплену автентифікацію без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове `persistence` — `runtime-only` для облікових даних, якими володіє CLI/app | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh tokens; оголосіть `contracts.externalAuthProviders` у manifest | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю за автентифікацією, підкріпленою env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають перемагати за пріоритетом | +| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, що належать провайдеру й ще не є в локальному реєстрі | Провайдер приймає довільні upstream-ідентифікатори моделей | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдер потребує мережевих метаданих перед розпізнаванням невідомих ідентифікаторів | +| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований runner використає розпізнану модель | Провайдер потребує переписувань транспорту, але все ще використовує core-транспорт | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах без перебирання ролі провайдера | +| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдер потребує очищення схем родини транспорту | +| 16 | `inspectToolSchemas` | Надає діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання core правилам, специфічним для провайдера | +| 17 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: нативний або tagged | Провайдер потребує tagged reasoning/фінального виводу замість нативних полів | +| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдер потребує типових параметрів запиту або очищення параметрів для окремого провайдера | +| 19 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдер потребує користувацького wire-протоколу, а не лише обгортки | +| 20 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдер потребує compat-обгорток заголовків/тіла/моделі запиту без користувацького транспорту | +| 21 | `resolveTransportTurnState` | Додає нативні per-turn транспортні заголовки або метадані | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність turn | +| 22 | `resolveWebSocketSessionPolicy` | Додає нативні WebSocket-заголовки або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або fallback-політику | +| 23 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає runtime-рядком `apiKey` | Провайдер зберігає додаткові метадані автентифікації та потребує користувацької форми runtime-токена | +| 24 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких endpoint refresh або політики refresh-failure | Провайдер не вписується у спільні refreshers `pi-ai` | +| 25 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли OAuth refresh зазнає невдачі | Провайдер потребує власних для провайдера вказівок з відновлення автентифікації після невдачі refresh | +| 26 | `matchesContextOverflowError` | Matcher переповнення context-window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б | +| 27 | `classifyFailoverReason` | Класифікація причини failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload/тощо | +| 28 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul провайдерів | Провайдер потребує проксі-специфічного обмеження cache TTL | +| 29 | `buildMissingAuthMessage` | Заміна для загального повідомлення відновлення при відсутній автентифікації | Провайдер потребує специфічної для провайдера підказки відновлення при відсутній автентифікації | +| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдер потребує синтетичних forward-compat рядків у `models list` і picker | +| 31 | `resolveThinkingProfile` | Набір рівнів `/think` для конкретної моделі, мітки відображення та типове значення | Провайдер надає користувацьку драбину thinking або бінарну мітку для вибраних моделей | +| 32 | `isBinaryThinking` | Compat-хук перемикача reasoning увімкнено/вимкнено | Провайдер надає лише бінарне thinking увімкнено/вимкнено | +| 33 | `supportsXHighThinking` | Compat-хук підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | +| 34 | `resolveDefaultThinkingLevel` | Compat-хук типового рівня `/think` | Провайдер володіє типовою політикою `/think` для родини моделей | +| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей | +| 36 | `prepareRuntimeAuth` | Обмін налаштованих облікових даних на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдер потребує обміну токена або короткочасних облікових даних запиту | +| 37 | `resolveUsageAuth` | Визначити облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Постачальнику потрібен користувацький розбір токена використання/квоти або інші облікові дані використання | +| 38 | `fetchUsageSnapshot` | Отримати й нормалізувати специфічні для постачальника знімки використання/квоти після визначення автентифікації | Постачальнику потрібна специфічна для постачальника кінцева точка використання або парсер корисного навантаження | +| 39 | `createEmbeddingProvider` | Побудувати належний постачальнику адаптер ембедингів для пам’яті/пошуку | Поведінка ембедингів пам’яті належить Plugin постачальника | +| 40 | `buildReplayPolicy` | Повернути політику повторного відтворення, що керує обробкою транскрипту для постачальника | Постачальнику потрібна користувацька політика транскрипту (наприклад, вилучення блоків мислення) | +| 41 | `sanitizeReplayHistory` | Переписати історію повторного відтворення після загального очищення транскрипту | Постачальнику потрібні специфічні для постачальника переписування повторного відтворення поза спільними допоміжними засобами Compaction | +| 42 | `validateReplayTurns` | Остаточна валідація або зміна форми ходів повторного відтворення перед вбудованим runner | Транспорт постачальника потребує суворішої валідації ходів після загальної санітизації | +| 43 | `onModelSelected` | Виконати належні постачальнику побічні ефекти після вибору | Постачальнику потрібна телеметрія або належний постачальнику стан, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють відповідний Plugin постачальника, а потім переходять до інших Plugin постачальників, -здатних до хуків, доки один із них фактично не змінить ідентифікатор моделі або -транспорт/конфігурацію. Це зберігає роботу alias/compat-шимів постачальників -без потреби для викликача знати, який bundled Plugin відповідає за переписування. -Якщо жоден хук постачальника не переписує підтримуваний запис конфігурації -сімейства Google, bundled нормалізатор конфігурації Google усе одно застосовує -це очищення сумісності. +здатних працювати з хуками, доки один із них фактично не змінить ідентифікатор +моделі або транспорт/конфігурацію. Це дає змогу shim-сумісності +alias/compat постачальників працювати без вимоги до викликача знати, який +вбудований Plugin володіє переписуванням. Якщо жоден хук постачальника не +переписує підтримуваний запис конфігурації Google-родини, вбудований нормалізатор +конфігурації Google усе одно застосує це очищення сумісності. -Якщо постачальнику потрібен повністю власний дротовий протокол або власний -виконавець запитів, це інший клас розширення. Ці хуки призначені для поведінки +Якщо постачальнику потрібен повністю власний wire protocol або власний виконавець +запитів, це інший клас розширення. Ці хуки призначені для поведінки постачальника, яка все ще працює у звичайному циклі інференсу OpenClaw. ### Приклад постачальника @@ -362,27 +367,27 @@ api.registerProvider({ ### Вбудовані приклади -Bundled Plugin постачальників поєднують наведені вище хуки, щоб відповідати -потребам каталогу, автентифікації, мислення, повторного відтворення та usage -кожного вендора. Авторитетний набір хуків розташований у кожному Plugin під -`extensions/`; ця сторінка ілюструє форми, а не дзеркально відтворює список. +Вбудовані Plugin постачальників поєднують наведені вище хуки, щоб відповідати +потребам каталогу, автентифікації, міркування, відтворення та використання кожного +постачальника. Авторитетний набір хуків міститься з кожним Plugin у `extensions/`; +ця сторінка ілюструє форми, а не дублює список. - + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати upstream - ідентифікатори моделей до статичного каталогу OpenClaw. + ідентифікатори моделей раніше за статичний каталог OpenClaw. - + GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`. - - Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, + + Спільні іменовані родини (`google-gemini`, `passthrough-gemini`, `anthropic-by-model`, `hybrid-anthropic-openai`) дають постачальникам змогу - підключатися до політики транскриптів через `buildReplayPolicy`, замість - того щоб кожен Plugin повторно реалізовував очищення. + підключатися до політики transcript через `buildReplayPolicy`, замість того + щоб кожен Plugin повторно реалізовував очищення. `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, @@ -390,18 +395,19 @@ Bundled Plugin постачальників поєднують наведені `volcengine` реєструють лише `catalog` і використовують спільний цикл інференсу. - - Beta-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині - публічного шва `api.ts` / `contract-api.ts` Plugin Anthropic + + Beta-заголовки, `/fast` / `serviceTier` і `context1m` містяться всередині + публічної межі `api.ts` / `contract-api.ts` Plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. -## Runtime-помічники +## Допоміжні засоби runtime -Plugin можуть отримувати доступ до вибраних core-помічників через `api.runtime`. Для TTS: +Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через +`api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -422,11 +428,11 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний core payload виводу TTS для поверхонь файлів/голосових нотаток. -- Використовує core конфігурацію `messages.tts` і вибір постачальника. -- Повертає PCM аудіобуфер + частоту дискретизації. Plugin мають виконати resample/encode для постачальників. -- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для voice picker або setup flows, якими володіє вендор. -- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості, для picker, обізнаних про постачальника. +- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію ядра `messages.tts` і вибір постачальника. +- Повертає аудіобуфер PCM + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для постачальників. +- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для засобів вибору голосу або потоків налаштування, якими володіє постачальник. +- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості для засобів вибору, обізнаних про постачальника. - OpenAI та ElevenLabs сьогодні підтримують телефонію. Microsoft не підтримує. Plugin також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. @@ -449,15 +455,15 @@ api.registerSpeechProvider({ Примітки: -- Тримайте політику TTS, fallback і доставлення відповіді в core. -- Використовуйте постачальників мовлення для синтезу, яким володіє вендор. -- Legacy вхід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`. -- Бажана модель володіння орієнтована на компанію: один Plugin вендора може володіти +- Залишайте політику TTS, fallback і доставку відповідей у ядрі. +- Використовуйте постачальників мовлення для поведінки синтезу, якою володіє постачальник. +- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`. +- Бажана модель володіння орієнтована на компанію: один Plugin постачальника може володіти постачальниками тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додає ці контракти можливостей. Для розуміння зображень/аудіо/відео Plugin реєструють одного типізованого -постачальника media-understanding замість generic key/value bag: +постачальника media-understanding замість загального набору ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -471,16 +477,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Тримайте оркестрацію, fallback, конфігурацію та прив’язку каналів у core. -- Тримайте поведінку вендора в Plugin постачальника. -- Additive розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові - поля результатів, нові необов’язкові можливості. +- Залишайте оркестрацію, fallback, конфігурацію та підключення каналів у ядрі. +- Залишайте поведінку постачальника в Plugin постачальника. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові + поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого патерну: - - core володіє контрактом можливості та runtime-помічником - - Plugin вендорів реєструють `api.registerVideoGenerationProvider(...)` - - Plugin функцій/каналів споживають `api.runtime.videoGeneration.*` + - ядро володіє контрактом можливості та допоміжним засобом runtime + - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)` + - Plugin функцій/каналів використовують `api.runtime.videoGeneration.*` -Для runtime-помічників media-understanding Plugin можуть викликати: +Для допоміжних засобів runtime media-understanding Plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -495,8 +501,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо Plugin можуть використовувати або runtime media-understanding, -або старіший alias STT: +Для транскрибування аудіо Plugin можуть використовувати або runtime +media-understanding, або старіший alias STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -511,11 +517,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для розуміння зображень/аудіо/відео. -- Використовує core аудіоконфігурацію media-understanding (`tools.media.audio`) і порядок fallback постачальників. -- Повертає `{ text: undefined }`, коли транскрипційний вивід не створено (наприклад, пропущений/непідтримуваний вхід). -- `api.runtime.stt.transcribeAudioFile(...)` залишається compatibility alias. +- Використовує аудіоконфігурацію ядра media-understanding (`tools.media.audio`) і порядок fallback постачальників. +- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, пропущений/непідтримуваний вхід). +- `api.runtime.stt.transcribeAudioFile(...)` залишається alias сумісності. -Plugin також можуть запускати фонові subagent runs через `api.runtime.subagent`: +Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -529,15 +535,15 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` є необов’язковими override для кожного run, а не постійними змінами сесії. -- OpenClaw враховує ці override-поля лише для trusted callers. -- Для fallback runs, якими володіє Plugin, оператори мають увімкнути `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити trusted Plugin конкретними canonical цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Untrusted subagent runs Plugin усе ще працюють, але override-запити відхиляються замість silent fallback. -- Subagent-сесії, створені Plugin, позначаються ідентифікатором Plugin, що їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці owned sessions; довільне видалення сесій усе ще потребує admin-scoped запиту Gateway. +- `provider` і `model` є необов’язковими перевизначеннями для окремого запуску, а не постійними змінами сесії. +- OpenClaw враховує ці поля перевизначення лише для довірених викликачів. +- Для fallback-запусків, якими володіє Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Недовірені subagent-запуски Plugin усе ще працюють, але запити перевизначення відхиляються, а не тихо переходять до fallback. +- Створені Plugin subagent-сесії позначаються ідентифікатором Plugin, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці власні сесії; довільне видалення сесій усе ще потребує admin-scoped запиту Gateway. -Для вебпошуку Plugin можуть споживати спільний runtime-помічник замість того, -щоб звертатися до прив’язки інструментів агента: +Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб runtime замість +доступу до підключення інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -558,8 +564,8 @@ Plugin також можуть реєструвати постачальникі Примітки: -- Тримайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у core. -- Використовуйте постачальників вебпошуку для специфічних для вендора пошукових транспортів. +- Залишайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у ядрі. +- Використовуйте постачальників вебпошуку для специфічних для постачальника транспортів пошуку. - `api.runtime.webSearch.*` є бажаною спільною поверхнею для Plugin функцій/каналів, яким потрібна пошукова поведінка без залежності від wrapper інструмента агента. ### `api.runtime.imageGeneration` @@ -575,12 +581,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюга постачальників image-generation. -- `listProviders(...)`: перелічити доступних постачальників image-generation та їхні можливості. +- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюга постачальників генерації зображень. +- `listProviders(...)`: перелічити доступних постачальників генерації зображень та їхні можливості. ## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP endpoints за допомогою `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP endpoint за допомогою `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -597,206 +603,206 @@ api.registerHttpRoute({ Поля маршруту: -- `path`: шлях маршруту під HTTP-сервером Gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію Gateway, або `"plugin"` для керованої Plugin автентифікації/перевірки Webhook. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для керованої Plugin автентифікації/перевірки webhook. - `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. - `replaceExisting`: необов’язкове. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту. -- `handler`: повертайте `true`, коли маршрут обробив запит. +- `handler`: поверніть `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було вилучено й спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` видалено, і це спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. - Маршрути Plugin мають явно оголошувати `auth`. -- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` тримайте лише на одному рівні автентифікації. -- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime-області. Вони призначені для керованих плагіном webhooks/перевірки підписів, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` виконуються всередині runtime-області запиту Gateway, але ця область навмисно консервативна: - - автентифікація bearer зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) фіксує runtime-області маршрутів плагіна на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному вході) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів плагіна з ідентичністю, runtime-область повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим автентифікації з ідентичністю та задокументуйте явний контракт заголовка `x-openclaw-scopes`. +- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Залишайте ланцюжки переходу `exact`/`prefix` лише на одному рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime scopes. Вони призначені для webhook/перевірки підписів, керованих plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) залишає runtime scopes маршрутів plugin прив'язаними до `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентифікацією (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршруту plugin з ідентифікацією, runtime scope повертається до `operator.write` +- Практичне правило: не вважайте plugin route з gateway-auth неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте auth-режим з ідентифікацією та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення нових плагінів використовуйте вузькі підшляхи SDK замість монолітного кореневого -barrel `openclaw/plugin-sdk`. Основні підшляхи: +Під час створення нових plugins використовуйте вузькі підшляхи SDK замість монолітного root barrel `openclaw/plugin-sdk`. +Основні підшляхи: -| Підшлях | Призначення | +| Підшлях | Призначення | | ----------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/збирання каналів | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби й парасольковий контракт | -| `openclaw/plugin-sdk/config-schema` | Схема Zod кореневого `openclaw.json` (`OpenClawSchema`) | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби entry/build для каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт | +| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) | -Плагіни каналів вибирають із сімейства вузьких швів — `channel-setup`, +Канальні plugins вибирають із сімейства вузьких меж — `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`. Поведінку затвердження слід консолідувати -на одному контракті `approvalCapability`, а не змішувати непов’язані -поля плагіна. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). +`channel-targets` і `channel-actions`. Поведінку схвалення слід консолідувати +на одному контракті `approvalCapability`, а не змішувати між непов'язаними +полями plugin. Див. [Канальні 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`, +`channel-activity-runtime` тощо). Віддавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` -замість широкого сумісного barrel `config-runtime`. +замість широкого compatibility barrel `config-runtime`. `openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime` -і `openclaw/plugin-sdk/infra-runtime` — це застарілі сумісні прошарки для -старіших плагінів. Новий код має імпортувати вужчі загальні примітиви. +і `openclaw/plugin-sdk/infra-runtime` є застарілими compatibility shims для +старіших plugins. Новий код має імпортувати вужчі загальні примітиви. -Внутрішні точки входу репозиторію (для кореня кожного вбудованого пакета плагіна): +Внутрішні entry points репозиторію (для кореня кожного bundled plugin package): -- `index.js` — точка входу вбудованого плагіна +- `index.js` — entry bundled plugin - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для runtime -- `setup-entry.js` — точка входу плагіна налаштування +- `setup-entry.js` — entry setup plugin -Зовнішні плагіни мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета плагіна з core або з іншого плагіна. -Точки входу, завантажені через фасад, надають перевагу активному знімку runtime-конфігурації, коли він -існує, а потім повертаються до розв’язаного конфігураційного файлу на диску. +Зовнішні plugins мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого plugin package з core або з іншого plugin. +Entry points, завантажені через facade, віддають перевагу активному знімку runtime config, якщо він +існує, а потім повертаються до розв'язаного config file на диску. -Підшляхи для конкретних можливостей, як-от `image-generation`, `media-understanding` -і `speech`, існують, бо вбудовані плагіни використовують їх сьогодні. Вони не є -автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну довідкову сторінку -SDK, коли покладаєтеся на них. +Підшляхи, специфічні для capabilities, як-от `image-generation`, `media-understanding` +і `speech`, існують, бо bundled plugins використовують їх сьогодні. Вони не є +автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну сторінку довідки SDK, +коли покладаєтеся на них. -## Схеми інструментів повідомлень +## Схеми message tool -Плагіни мають володіти специфічними для каналу внесками схеми `describeMessageTool(...)` -для примітивів, що не є повідомленнями, як-от реакції, прочитання й опитування. -Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` -замість нативних для провайдера полів кнопок, компонентів, блоків або карток. -Див. [Подання повідомлення](/uk/plugins/message-presentation) щодо контракту, -правил fallback, зіставлення провайдерів і контрольного списку автора плагіна. +Plugins мають володіти внесками до channel-specific схеми `describeMessageTool(...)` +для не-message примітивів, як-от reactions, reads і polls. +Спільна presentation для надсилання має використовувати загальний контракт `MessagePresentation` +замість provider-native полів button, component, block або card. +Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту, +правил fallback, provider mapping і checklist для автора plugin. -Плагіни з можливістю надсилання оголошують, що вони можуть рендерити, через можливості повідомлень: +Plugins, здатні надсилати повідомлення, оголошують, що вони можуть відтворювати, через message capabilities: -- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів закріпленої доставки +- `presentation` для semantic presentation blocks (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів pinned-delivery -Core вирішує, чи рендерити подання нативно, чи деградувати його до тексту. -Не відкривайте нативні для провайдера UI-обхідні шляхи з загального інструмента повідомлень. -Застарілі допоміжні засоби SDK для застарілих нативних схем залишаються експортованими для наявних -сторонніх плагінів, але нові плагіни не повинні їх використовувати. +Core вирішує, чи відтворювати presentation нативно, чи деградувати її до тексту. +Не відкривайте provider-native UI escape hatches із загального message tool. +Застарілі допоміжні засоби SDK для legacy native schemas залишаються експортованими для наявних +сторонніх plugins, але нові plugins не повинні їх використовувати. -## Розв’язання цілі каналу +## Розв'язання цілі каналу -Плагіни каналів мають володіти специфічною для каналу семантикою цілей. Тримайте спільний -outbound host загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера: +Канальні plugins мають володіти channel-specific семантикою цілей. Залишайте спільний +outbound host загальним і використовуйте поверхню messaging adapter для правил provider: - `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль - слід трактувати як `direct`, `group` або `channel` перед пошуком у каталозі. + слід трактувати як `direct`, `group` або `channel` перед пошуком у directory. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - введення має одразу перейти до id-подібного розв’язання замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли - core потребує остаточного розв’язання, що належить провайдеру, після нормалізації або після - промаху в каталозі. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, - специфічною для провайдера, після розв’язання цілі. + input має одразу перейти до id-like resolution замість directory search. +- `messaging.targetResolver.resolveTarget(...)` є fallback plugin, коли + core потребує остаточного provider-owned resolution після нормалізації або після + directory miss. +- `messaging.resolveOutboundSessionRoute(...)` володіє provider-specific побудовою маршруту сесії, + коли ціль розв'язано. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися перед +- Використовуйте `inferTargetChatType` для category decisions, які мають відбуватися перед пошуком peers/groups. -- Використовуйте `looksLikeId` для перевірок "трактувати це як явний/нативний id цілі". -- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для - широкого пошуку в каталозі. -- Тримайте нативні для провайдера id, як-от chat ids, thread ids, JIDs, handles і room - ids, усередині значень `target` або специфічних для провайдера параметрів, а не в загальних полях SDK. +- Використовуйте `looksLikeId` для перевірок "трактувати це як explicit/native target id". +- Використовуйте `resolveTarget` для provider-specific normalization fallback, а не для + широкого directory search. +- Зберігайте provider-native ids, як-от chat ids, thread ids, JIDs, handles і room + ids, усередині значень `target` або provider-specific params, а не в загальних полях SDK. -## Каталоги на основі конфігурації +## Довідники на основі конфігурації -Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в -плагіні та повторно використовувати спільні допоміжні засоби з +Plugins, які виводять directory entries з конфігурації, мають тримати цю логіку в +plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, як-от: -- DM peers, керовані allowlist -- налаштовані мапи каналів/груп -- статичні fallback каталогу в межах облікового запису +- peers для DM, керовані allowlist +- налаштовані channel/group maps +- account-scoped static directory fallbacks Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрація запитів -- застосування ліміту -- допоміжні засоби дедуплікації/нормалізації -- побудова `ChannelDirectoryEntry[]` +- фільтрацію запитів +- застосування limit +- допоміжні засоби deduping/normalization +- побудову `ChannelDirectoryEntry[]` -Специфічна для каналу перевірка облікового запису й нормалізація id мають залишатися в -реалізації плагіна. +Channel-specific inspection облікового запису та нормалізація id мають залишатися в +реалізації plugin. -## Каталоги провайдерів +## Каталоги provider -Плагіни провайдерів можуть визначати каталоги моделей для inference за допомогою +Provider plugins можуть визначати каталоги моделей для inference за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: -- `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдера +- `{ provider }` для одного provider entry +- `{ providers }` для кількох provider entries -Використовуйте `catalog`, коли плагін володіє специфічними для провайдера id моделей, типовими значеннями -base URL або метаданими моделей, обмеженими автентифікацією. +Використовуйте `catalog`, коли plugin володіє provider-specific model ids, base URL +defaults або auth-gated model metadata. -`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих -неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог plugin об'єднується відносно +вбудованих implicit providers OpenClaw: -- `simple`: прості провайдери на основі API-ключа або env -- `profile`: провайдери, що з’являються, коли існують профілі автентифікації -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів -- `late`: останній прохід, після інших неявних провайдерів +- `simple`: звичайні providers, керовані API key або env +- `profile`: providers, що з'являються, коли існують auth profiles +- `paired`: providers, що синтезують кілька пов'язаних provider entries +- `late`: останній прохід, після інших implicit providers -Пізніші провайдери перемагають під час колізії ключів, тож плагіни можуть навмисно перевизначити -вбудований запис провайдера з тим самим id провайдера. +Пізніші providers перемагають під час key collision, тому plugins можуть навмисно перевизначати +вбудований provider entry з тим самим provider id. Сумісність: -- `discovery` досі працює як застарілий псевдонім +- `discovery` досі працює як legacy alias - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Read-only перевірка каналу +## Read-only inspection каналу -Якщо ваш плагін реєструє канал, надавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. +Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це runtime-шлях. Йому дозволено припускати, що облікові дані +- `resolveAccount(...)` — це runtime path. Він може припускати, що credentials повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні secrets відсутні. -- Read-only шляхи команд, як-от `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/відновлення конфігурації - не повинні матеріалізувати runtime-облікові дані лише для того, щоб - описати конфігурацію. +- Read-only command paths, як-от `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config + repair, не повинні матеріалізувати runtime credentials лише для + опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертайте лише описовий стан облікового запису. - Зберігайте `enabled` і `configured`. -- Додавайте поля джерела/стану облікових даних, коли доречно, як-от: +- Додавайте поля source/status для credentials, коли доречно, як-от: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення токенів лише для звітування про read-only - доступність. Повернення `tokenStatus: "available"` (і відповідного поля джерела) - достатньо для команд у стилі status. -- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але - недоступні в поточному шляху команди. +- Вам не потрібно повертати сирі значення token лише для повідомлення read-only + availability. Повернення `tokenStatus: "available"` (і відповідного поля source) + достатньо для status-style commands. +- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але + він недоступний у поточному command path. -Це дає змогу read-only командам повідомляти "налаштовано, але недоступно в цьому шляху -команди" замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. +Це дає read-only commands змогу повідомляти "configured but unavailable in this command +path" замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштований. -## Пакети пакетів +## Пакети package -Каталог плагіна може містити `package.json` з `openclaw.extensions`: +Каталог plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -808,58 +814,58 @@ base URL або метаданими моделей, обмеженими авт } ``` -Кожен запис стає плагіном. Якщо пакет перелічує кілька extensions, id плагіна +Кожен entry стає plugin. Якщо pack перелічує кілька extensions, plugin id стає `name/`. -Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб +Якщо ваш plugin імпортує npm deps, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна -після розв’язання symlink. Записи, що виходять за межі каталогу пакета, +Security guardrail: кожен entry `openclaw.extensions` має залишатися всередині каталогу plugin +після розв'язання symlink. Entries, що виходять за межі package directory, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна за допомогою -локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, -без dev dependencies під час runtime), ігноруючи успадковані глобальні налаштування npm install. -Тримайте дерева залежностей плагінів "чистими JS/TS" і уникайте пакетів, які потребують -збірок `postinstall`. +Security note: `openclaw plugins install` встановлює залежності plugin за допомогою +project-local `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, +без dev dependencies під час runtime), ігноруючи успадковані global npm install settings. +Тримайте дерева залежностей plugin "pure JS/TS" і уникайте package, які потребують +`postinstall` builds. -Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого плагіна каналу або -коли плагін каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повної точки входу плагіна. Це робить запуск і налаштування легшими, -коли основна точка входу вашого плагіна також під’єднує інструменти, hooks або інший runtime-only -код. +Необов'язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. +Коли OpenClaw потребує setup surfaces для вимкненого channel plugin або +коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повного plugin entry. Це полегшує startup і setup, +коли ваш main plugin entry також під'єднує tools, hooks або інший runtime-only +code. -Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску Gateway -до початку прослуховування, навіть коли канал уже налаштований. +Необов'язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +може перевести channel plugin на той самий шлях `setupEntry` під час pre-listen startup phase +gateway, навіть коли канал уже налаштований. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як Gateway почне слухати. На практиці це означає, що точка входу налаштування -має зареєструвати кожну належну каналу можливість, від якої залежить запуск, як-от: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup surface, яка має існувати +до того, як gateway почне слухати. На практиці це означає, що setup entry +має зареєструвати кожну channel-owned capability, від якої залежить startup, як-от: - сама реєстрація каналу -- будь-які HTTP-маршрути, які мають бути доступні до того, як Gateway почне слухати -- будь-які методи Gateway, інструменти або сервіси, які мають існувати протягом того самого вікна +- будь-які HTTP routes, які мають бути доступні до того, як gateway почне слухати +- будь-які gateway methods, tools або services, які мають існувати протягом того самого вікна -Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште плагін на стандартній поведінці й дозвольте OpenClaw завантажувати -повну точку входу під час запуску. +Якщо ваш full entry досі володіє будь-якою required startup capability, не вмикайте +цей flag. Залиште plugin на default behavior і дозвольте OpenClaw завантажити +full entry під час startup. -Вбудовані канали також можуть публікувати setup-only допоміжні засоби контрактної поверхні, які core -може консультувати до завантаження повного runtime каналу. Поточна поверхня просування налаштування: +Bundled channels також можуть публікувати setup-only contract-surface helpers, до яких core +може звертатися до завантаження повного channel runtime. Поточна setup +promotion surface така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу Plugin. -Matrix є поточним вбудованим прикладом: він переміщує лише ключі автентифікації/bootstrap у названий підвищений обліковий запис, коли названі облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. +Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу плагіна. Matrix є поточним вбудованим прикладом: він переносить лише ключі автентифікації/початкового завантаження до іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів налаштування залишають виявлення вбудованої контрактної поверхні лінивим. Час імпорту залишається легким; поверхня підвищення завантажується лише під час першого використання, замість повторного входу в запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають виявлення вбудованої поверхні контракту лінивим. Час імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання, замість повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску містять методи RPC Gateway, тримайте їх на префіксі, специфічному для Plugin. Простори імен адміністратора Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються в `operator.admin`, навіть якщо Plugin запитує вужчу область. +Коли ці стартові поверхні містять RPC-методи Gateway, тримайте їх на префіксі, специфічному для плагіна. Простори імен адміністрування Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються до `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -878,7 +884,7 @@ Matrix є поточним вбудованим прикладом: він пе ### Метадані каталогу каналів -Plugins каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це залишає каталог Core без даних. +Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це дає змогу Core не містити даних каталогу. Приклад: @@ -908,18 +914,18 @@ Plugins каналів можуть оголошувати метадані на Корисні поля `openclaw.channel` поза мінімальним прикладом: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану -- `docsLabel`: перевизначити текст посилання для посилання на документацію -- `preferOver`: ідентифікатори Plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати +- `detailLabel`: вторинна мітка для насиченіших поверхонь каталогу/стану +- `docsLabel`: перевизначає текст посилання для посилання на документацію +- `preferOver`: ідентифікатори плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору -- `markdownCapable`: позначає канал як здатний працювати з Markdown для рішень щодо вихідного форматування -- `exposure.configured`: приховати канал із поверхонь списку налаштованих каналів, коли встановлено `false` -- `exposure.setup`: приховати канал з інтерактивних засобів вибору налаштування/конфігурування, коли встановлено `false` -- `exposure.docs`: позначити канал як внутрішній/приватний для поверхонь навігації документації +- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування +- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурування, коли встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` -- `quickstartAllowFrom`: увімкнути канал у стандартний потік швидкого старту `allowFrom` -- `forceAccountBinding`: вимагати явного прив’язування облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддавати перевагу пошуку сеансу під час розв’язання цілей оголошення +- `quickstartAllowFrom`: вмикає канал у стандартний потік швидкого старту `allowFrom` +- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сеансу під час розв’язання цілей оголошень OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). Помістіть JSON-файл в одне з таких місць: @@ -927,19 +933,17 @@ 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-специфікація є точною версією або плаваючим селектором, чи наявні очікувані метадані цілісності, і чи також доступний локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібрана назва npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, і коли метадані цілісності npm наявні без дійсного джерела npm. Споживачі мають трактувати `installSource` як додаткове необов’язкове поле, щоб записи, створені вручну, і прокладки каталогу не мусили його синтезувати. -Це дає онбордингу та діагностиці змогу пояснювати стан площини джерел без імпортування runtime Plugin. +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів показують нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані факти визначають, чи є npm-специфікація точною версією або плаваючим селектором, чи присутні очікувані метадані цілісності та чи доступний також локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, а також коли метадані цілісності npm присутні без дійсного джерела npm. Споживачі мають розглядати `installSource` як додаткове необов’язкове поле, щоб записи, створені вручну, і прокладки каталогу не мусили його синтезувати. Це дає змогу онбордингу й діагностиці пояснювати стан площини джерел без імпорту середовища виконання плагіна. -Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із `expectedIntegrity`. Голі назви пакетів і dist-tags усе ще працюють для сумісності, але вони показують попередження площини джерел, щоб каталог міг рухатися до закріплених встановлень із перевіркою цілісності без порушення наявних Plugins. -Коли онбординг встановлює з локального шляху каталогу, він записує керований запис індексу Plugin із `source: "path"` і відносним до робочого простору `sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довготривалу конфігурацію. Це залишає локальні встановлення для розробки видимими для діагностики площини джерел без додавання другої поверхні розкриття сирого шляху файлової системи. Збережений індекс Plugin `plugins/installs.json` є джерелом істини для джерела встановлення і може оновлюватися без завантаження runtime-модулів Plugin. Його мапа `installRecords` є довговічною, навіть коли маніфест Plugin відсутній або недійсний; його масив `plugins` є відновлюваним представленням маніфестів. +Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із `expectedIntegrity`. Голі імена пакетів і dist-tag-и все ще працюють для сумісності, але вони показують попередження площини джерел, щоб каталог міг рухатися до закріплених встановлень із перевіркою цілісності без ламання наявних плагінів. Коли онбординг встановлює з локального шляху каталогу, він записує керований запис індексу плагіна з `source: "path"` і відносним до робочої області `sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довготривалу конфігурацію. Це зберігає встановлення для локальної розробки видимими для діагностики площини джерел без додавання другої сирої поверхні розкриття шляху файлової системи. Збережений індекс плагінів `plugins/installs.json` є джерелом істини для встановлення й може оновлюватися без завантаження модулів середовища виконання плагінів. Його мапа `installRecords` є довговічною навіть тоді, коли маніфест плагіна відсутній або недійсний; його масив `plugins` є перебудовуваним поданням маніфесту. -## Plugins контекстного рушія +## Плагіни контекстного рушія -Plugins контекстного рушія володіють оркестрацією контексту сеансу для приймання, складання та Compaction. Зареєструйте їх зі свого Plugin через `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій за допомогою `plugins.slots.contextEngine`. +Плагіни контекстного рушія відповідають за оркестрацію контексту сеансу для приймання, збирання та Compaction. Зареєструйте їх зі свого плагіна через `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій за допомогою `plugins.slots.contextEngine`. -Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий конвеєр контексту, а не просто додати пошук у пам’яті чи hooks. +Використовуйте це, коли вашому плагіну потрібно замінити або розширити стандартний конвеєр контексту, а не просто додати пошук пам’яті чи хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -967,9 +971,9 @@ export default function (api) { } ``` -Фабрика `ctx` надає необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час конструювання. +Фабрика `ctx` надає необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час створення. -Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і делегуйте його явно: +Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і явно делегуйте його: ```ts import { @@ -1006,41 +1010,41 @@ export default function (api) { ## Додавання нової можливості -Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте систему Plugin приватним проникненням усередину. Додайте відсутню можливість. +Коли плагіну потрібна поведінка, яка не вкладається в поточний API, не обходьте систему плагінів приватним проникненням усередину. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт Core - Вирішіть, якою спільною поведінкою має володіти Core: політикою, fallback, злиттям конфігурації, життєвим циклом, семантикою для каналів і формою runtime helper. -2. додайте типізовані поверхні реєстрації/runtime Plugin + Вирішіть, яку спільну поведінку має контролювати Core: політику, резервний шлях, об’єднання конфігурації, життєвий цикл, семантику для каналів і форму допоміжного засобу середовища виконання. +2. додайте типізовані поверхні реєстрації/середовища виконання плагіна Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. з’єднайте Core + споживачів каналів/функцій - Канали та функціональні Plugins мають споживати нову можливість через Core, а не шляхом прямого імпорту реалізації постачальника. +3. під’єднайте споживачів Core + каналів/функцій + Канали й функціональні плагіни мають споживати нову можливість через Core, а не імпортувати реалізацію постачальника напряму. 4. зареєструйте реалізації постачальників - Plugins постачальників потім реєструють свої бекенди для цієї можливості. + Потім плагіни постачальників реєструють свої бекенди для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. + Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною. -Так OpenClaw залишається принциповим, не стаючи жорстко закодованим під світогляд одного провайдера. Див. [кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного контрольного списку файлів і пропрацьованого прикладу. +Саме так OpenClaw залишається принциповим, не стаючи жорстко прив’язаним до світогляду одного провайдера. Див. [Кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного контрольного списку файлів і опрацьованого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих поверхонь разом: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких поверхонь: - типи контракту Core у `src//types.ts` -- runner/runtime helper Core у `src//runtime.ts` -- поверхня реєстрації API Plugin у `src/plugins/types.ts` -- підключення реєстру Plugin у `src/plugins/registry.ts` -- runtime-експозиція Plugin у `src/plugins/runtime/*`, коли функціональні/канальні Plugins мають її споживати -- helpers захоплення/тестів у `src/test-utils/plugin-registration.ts` -- твердження володіння/контракту в `src/plugins/contracts/registry.ts` -- документація оператора/Plugin у `docs/` +- допоміжний засіб запуску/середовища виконання Core у `src//runtime.ts` +- поверхня реєстрації API плагіна у `src/plugins/types.ts` +- під’єднання реєстру плагінів у `src/plugins/registry.ts` +- експонування середовища виконання плагіна у `src/plugins/runtime/*`, коли функціональним/канальним плагінам потрібно його споживати +- допоміжні засоби захоплення/тестування у `src/test-utils/plugin-registration.ts` +- твердження про володіння/контракт у `src/plugins/contracts/registry.ts` +- документація для оператора/плагіна у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості -Мінімальний патерн: +Мінімальний шаблон: ```ts // core contract @@ -1066,22 +1070,22 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Патерн тесту контракту: +Шаблон тесту контракту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це залишає правило простим: +Це зберігає правило простим: - Core володіє контрактом можливості + оркестрацією -- Plugins постачальників володіють реалізаціями постачальників -- функціональні/канальні Plugins споживають runtime helpers -- тести контракту залишають володіння явним +- плагіни постачальників володіють реалізаціями постачальників +- функціональні/канальні плагіни споживають допоміжні засоби середовища виконання +- тести контракту зберігають володіння явним ## Пов’язане -- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми -- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) -- [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugins](/uk/plugins/building-plugins) +- [Архітектура плагінів](/uk/plugins/architecture) — публічна модель і форми можливостей +- [Підшляхи SDK плагінів](/uk/plugins/sdk-subpaths) +- [Налаштування SDK плагінів](/uk/plugins/sdk-setup) +- [Створення плагінів](/uk/plugins/building-plugins)