From 9baaf1c50fb1f02a9d5677ef8d6b251bc97e55b6 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 12 Apr 2026 02:35:43 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/architecture.md | 1341 +++++++++++++++---------------- docs/uk/plugins/manifest.md | 440 +++++----- 2 files changed, 891 insertions(+), 890 deletions(-) diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index c6a9d1b7c..cd25a87a8 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -3,183 +3,173 @@ read_when: - Створення або налагодження нативних плагінів OpenClaw - Розуміння моделі можливостей плагінів або меж володіння - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація хуків середовища виконання постачальника або плагінів каналів + - Реалізація хуків середовища виконання провайдера або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішня структура плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' -title: Внутрішня структура плагінів +summary: 'Внутрішні компоненти плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' +title: Внутрішні компоненти плагінів x-i18n: - generated_at: "2026-04-11T11:37:27Z" + generated_at: "2026-04-12T02:30:58Z" model: gpt-5.4 provider: openai - source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 + source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішня структура плагінів +# Внутрішні компоненти плагінів - Це **довідник із глибокої архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача - - [Початок роботи](/uk/plugins/building-plugins) — перший посібник зі створення плагіна + Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувачів + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення плагіна - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей - - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації + - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей + - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації -Ця сторінка описує внутрішню архітектуру системи плагінів OpenClaw. +На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен +Можливості — це публічна модель **нативних плагінів** всередині OpenClaw. Кожен нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади плагінів | -| --------------------- | ---------------------------------------------- | ------------------------------------ | -| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI-бекенд інференсу | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Можливість | Метод реєстрації | Приклади плагінів | +| ---------------------- | --------------------------------------------- | ------------------------------------ | +| Текстовий висновок | `api.registerProvider(...)` | `openai`, `anthropic` | +| Серверна частина висновку CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веботримання | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або -служби, є **застарілим плагіном лише з хуками**. Цей шаблон усе ще повністю підтримується. +сервіси, є **застарілим плагіном лише з хуками**. Цей шаблон і далі повністю підтримується. ### Позиція щодо зовнішньої сумісності -Модель можливостей уже впроваджена в core і сьогодні використовується +Модель можливостей уже впроваджена в ядрі та сьогодні використовується вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще -потребує вищої планки, ніж «це експортується, отже це зафіксовано». +потребує вищої планки, ніж «це експортується, отже це вже незмінний контракт». Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; розглядайте - це як базовий рівень сумісності -- **нові вбудовані/нативні плагіни:** надавайте перевагу явній реєстрації можливостей замість - vendor-specific доступу до внутрішніх частин або нових рішень лише з хуками -- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але - вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, якщо в документації контракт явно не позначено як стабільний +- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте це базовим рівнем сумісності +- **нові вбудовані/нативні плагіни:** надавайте перевагу явній реєстрації можливостей замість vendor-специфічних проникнень усередину або нових дизайнів лише з хуками +- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але вважайте допоміжні поверхні, специфічні для можливостей, такими, що ще розвиваються, якщо в документації контракт не позначено явно як стабільний Практичне правило: -- API реєстрації можливостей — це цільовий напрямок -- застарілі хуки залишаються найбезпечнішим шляхом без поломок для зовнішніх плагінів під час - переходу -- не всі експортовані підшляхи однакові; віддавайте перевагу вузькому документованому - контракту, а не випадковим допоміжним експортам +- API реєстрації можливостей — це бажаний напрям +- застарілі хуки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час переходу +- не всі експортовані допоміжні підшляхи однаково важливі; віддавайте перевагу вузькому задокументованому контракту, а не випадковим допоміжним експортам ### Форми плагінів OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки під час реєстрації, а не лише статичних метаданих: +поведінки реєстрації (а не лише статичних метаданих): -- **plain-capability** -- реєструє рівно один тип можливості (наприклад, - плагін лише постачальника, як-от `mistral`) -- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовим інференсом, мовленням, розумінням медіа та - генерацією зображень) -- **hook-only** -- реєструє лише хуки (типізовані або власні), без можливостей, - інструментів, команд чи служб -- **non-capability** -- реєструє інструменти, команди, служби або маршрути, але без - можливостей +- **plain-capability** -- реєструє рівно один тип можливості (наприклад, плагін лише провайдера, такий як `mistral`) +- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим висновком, мовленням, розумінням медіа та генерацією зображень) +- **hook-only** -- реєструє лише хуки (типізовані або користувацькі), без можливостей, інструментів, команд чи сервісів +- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості -Використовуйте `openclaw plugins inspect `, щоб переглянути форму плагіна та -розподіл можливостей. Докладніше дивіться в [довіднику CLI](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та +розподіл за можливостями. Докладніше дивіться у [довідці CLI](/cli/plugins#inspect). ### Застарілі хуки -Хук `before_agent_start` і далі підтримується як шлях сумісності для -плагінів лише з хуками. На нього досі спираються реальні застарілі плагіни. +Хук `before_agent_start` і далі підтримується як шлях сумісності для плагінів +лише з хуками. Від нього все ще залежать застарілі реальні плагіни. Напрямок: - зберігати його працездатність - документувати його як застарілий -- для роботи з перевизначенням моделі/постачальника надавати перевагу `before_model_resolve` -- для зміни prompt надавати перевагу `before_prompt_build` -- видаляти лише після падіння реального використання та коли покриття фікстурами підтвердить безпечність міграції +- надавати перевагу `before_model_resolve` для роботи з перевизначенням моделі/провайдера +- надавати перевагу `before_prompt_build` для роботи з мутацією промпта +- видаляти лише після зниження реального використання та підтвердження безпечності міграції покриттям через фікстури ### Сигнали сумісності -Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете -побачити одну з таких позначок: +Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити +одну з таких міток: | Сигнал | Значення | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація коректно розбирається, а плагіни успішно визначаються | +| **config valid** | Конфігурація успішно розбирається, а плагіни коректно визначаються | | **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | +| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | +| **hard error** | Конфігурація недійсна або не вдалося завантажити плагін | -Ані `hook-only`, ані `before_agent_start` не зламають ваш плагін сьогодні -- -`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці +Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш плагін -- +`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури -Система плагінів OpenClaw має чотири рівні: +Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить кандидатів у плагіни за налаштованими шляхами, коренями workspace, - глобальними коренями розширень і вбудованими розширеннями. Під час виявлення спочатку читаються - нативні маніфести `openclaw.plugin.json` і підтримувані маніфести bundle. + OpenClaw знаходить потенційні плагіни в налаштованих шляхах, коренях робочих просторів, + глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку зчитує + нативні маніфести `openclaw.plugin.json` разом із підтримуваними маніфестами збірок. 2. **Увімкнення + валідація** - Core вирішує, чи знайдений плагін увімкнено, вимкнено, заблоковано, чи + Ядро визначає, чи виявлений плагін увімкнено, вимкнено, заблоковано, чи вибрано для ексклюзивного слота, наприклад пам’яті. -3. **Завантаження в середовищі виконання** +3. **Завантаження під час виконання** Нативні плагіни OpenClaw завантажуються в межах процесу через jiti і реєструють - можливості в центральному реєстрі. Сумісні bundle нормалізуються в записи + можливості в центральному реєстрі. Сумісні збірки нормалізуються в записи реєстру без імпорту коду середовища виконання. 4. **Споживання поверхонь** - Решта OpenClaw читає реєстр, щоб надати інструменти, канали, налаштування постачальників, - хуки, HTTP-маршрути, команди CLI та служби. + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування провайдерів, + хуки, HTTP-маршрути, команди CLI та сервіси. -Для CLI плагінів зокрема виявлення кореневих команд поділено на дві фази: +Спеціально для CLI плагінів виявлення кореневих команд розділено на дві фази: -- метадані часу розбору надходять із `registerCli(..., { descriptors: [...] })` -- справжній модуль CLI плагіна може залишатися ледачим і реєструватися під час першого виклику +- метадані під час розбору надходять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику -Це дозволяє зберігати CLI-код, що належить плагіну, всередині плагіна й водночас дає OpenClaw -змогу зарезервувати імена кореневих команд до початку розбору. +Це дозволяє зберігати код CLI, що належить плагіну, всередині самого плагіна, +водночас даючи змогу OpenClaw резервувати імена кореневих команд до початку розбору. Важлива межа проєктування: -- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** +- виявлення та валідація конфігурації мають працювати з **метаданих маніфесту/схеми** без виконання коду плагіна -- нативна поведінка середовища виконання надходить із шляху `register(api)` модуля плагіна +- нативна поведінка під час виконання надходить зі шляху `register(api)` модуля плагіна -Таке розділення дає OpenClaw змогу валідовувати конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки для UI/схеми ще до повної активації середовища виконання. +Такий поділ дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки для UI/схеми до активації повного середовища виконання. ### Плагіни каналів і спільний інструмент повідомлень -Плагінам каналів не потрібно реєструвати окремий інструмент надсилання/редагування/реакції для -звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core, а -плагіни каналів володіють специфічними для каналу виявленням і виконанням за ним. +Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для +звичайних дій у чаті. OpenClaw підтримує один спільний інструмент `message` у ядрі, +а плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. Поточна межа така: -- core володіє хостом спільного інструмента `message`, підключенням до prompt, - обліком сесій/тредів і диспетчеризацією виконання -- плагіни каналів володіють виявленням дій у межах області, виявленням - можливостей і будь-якими фрагментами схеми, специфічними для каналу -- плагіни каналів володіють граматикою розмов сесії, специфічною для постачальника, зокрема - тим, як id розмов кодують id тредів або успадковуються від батьківських розмов -- плагіни каналів виконують фінальну дію через свій адаптер дій +- ядро володіє хостом спільного інструмента `message`, прив’язкою до промпта, обліком сесій/гілок + і диспетчеризацією виконання +- плагіни каналів володіють виявленням дій в обмеженій області, виявленням можливостей і будь-якими + фрагментами схеми, специфічними для каналу +- плагіни каналів володіють граматикою сесійної розмови, специфічною для провайдера, наприклад тим, + як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов +- плагіни каналів виконують кінцеву дію через свій адаптер дій -Для плагінів каналів поверхнею SDK є -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну повертати свої видимі дії, можливості та внески в схему +Для плагінів каналів поверхня SDK — це +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик +виявлення дає плагіну змогу повертати його видимі дії, можливості та внески в схему разом, щоб ці частини не розходилися. -Core передає область середовища виконання на цей крок виявлення. Важливі поля включають: +Ядро передає область виконання в цей крок виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -190,124 +180,124 @@ Core передає область середовища виконання на - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для контекстно-чутливих плагінів. Канал може приховувати або відкривати -дії з повідомленнями залежно від активного облікового запису, поточної кімнати/треду/повідомлення або -довіреної ідентичності запитувача без жорстко закодованих гілок, специфічних для каналу, у -core-інструменті `message`. +Це важливо для контекстно-залежних плагінів. Канал може приховувати або показувати +дії з повідомленнями залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або +довіреної ідентичності запитувача без жорстко закодованих розгалужень, специфічних для каналу, +в основному інструменті `message`. -Саме тому зміни маршрутизації embedded-runner усе ще залишаються роботою плагіна: runner -відповідає за передавання поточної ідентичності чату/сесії в межу виявлення плагіна, щоб -спільний інструмент `message` відкривав правильну поверхню, що належить каналу, -для поточного ходу. +Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагінів: виконавець +відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб +спільний інструмент `message` надавав правильну поверхню, що належить каналу, +для поточного кроку. -Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати -runtime виконання всередині власних модулів розширення. Core більше не володіє -runtime дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані -плагіни мають імпортувати свій локальний runtime-код безпосередньо зі своїх +Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають +тримати середовище виконання всередині власних модулів розширення. Ядро більше не володіє +середовищами виконання дій з повідомленнями Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані +плагіни мають імпортувати свій локальний код середовища виконання безпосередньо зі своїх модулів, що належать розширенню. -Та сама межа застосовується і до SDK-швів із назвами постачальників загалом: core не має -імпортувати зручні barrel-модулі, специфічні для каналів Slack, Discord, Signal, -WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, слід або -використати власний barrel `api.ts` / `runtime-api.ts` вбудованого плагіна, або підняти цю потребу -до вузької загальної можливості в спільному SDK. +Та сама межа застосовується до іменованих за провайдерами поверхонь SDK загалом: ядро не повинно +імпортувати зручні барелі, специфічні для каналу, для Slack, Discord, Signal, +WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, воно має або +використовувати власний барель `api.ts` / `runtime-api.ts` вбудованого плагіна, або +підняти цю потребу до вузької загальної можливості в спільному SDK. -Зокрема для опитувань є два шляхи виконання: +Спеціально для опитувань є два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, які відповідають загальній +- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній моделі опитувань -- `actions.handleAction("poll")` — пріоритетний шлях для специфічної для каналу - семантики опитувань або додаткових параметрів опитування +- `actions.handleAction("poll")` — це бажаний шлях для семантики опитувань, + специфічної для каналу, або додаткових параметрів опитувань -Тепер Core відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна -відхиляє дію, тож обробники опитувань, що належать плагіну, можуть приймати специфічні для каналу -поля опитувань, не блокуючись спершу загальним парсером опитувань. +Тепер ядро відкладає спільний розбір опитувань доти, доки диспетчеризація опитувань плагіна +не відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати +специфічні для каналу поля опитувань без блокування з боку загального розбірника опитувань. -Повну послідовність запуску дивіться в [Конвеєр завантаження](#load-pipeline). +Повну послідовність запуску дивіться в [Конвеєрі завантаження](#load-pipeline). ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір не пов’язаних між собою інтеграцій. +**функціональності**, а не як набір не пов’язаних між собою інтеграцій. -Це означає: +Це означає, що: -- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, пов’язаними з цією компанією -- плагін функції зазвичай має володіти повною поверхнею функції, яку він додає -- канали мають споживати спільні можливості core, а не перевпроваджувати - поведінку постачальника ситуативно +- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що стосуються цієї компанії +- плагін функціональності зазвичай має володіти всією поверхнею цієї функціональності, яку він вводить +- канали мають споживати спільні можливості ядра, а не довільно повторно реалізовувати + поведінку провайдера Приклади: -- вбудований плагін `openai` володіє поведінкою постачальника моделей OpenAI і поведінкою OpenAI для - мовлення + голосу в реальному часі + розуміння медіа + генерації зображень -- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs -- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft -- вбудований плагін `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google для - розуміння медіа + генерації зображень + вебпошуку -- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для веботримання +- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та поведінкою OpenAI + для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований плагін `elevenlabs` володіє поведінкою ElevenLabs для мовлення +- вбудований плагін `microsoft` володіє поведінкою Microsoft для мовлення +- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google + для розуміння медіа + генерації зображень + вебпошуку +- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для отримання вебданих - вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми - бекендами розуміння медіа -- вбудований плагін `qwen` володіє поведінкою текстового постачальника Qwen, а також - поведінкою розуміння медіа і генерації відео -- плагін `voice-call` — це плагін функції: він володіє транспортом викликів, інструментами, + серверними частинами розуміння медіа +- вбудований плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також + поведінкою для розуміння медіа та генерації відео +- плагін `voice-call` — це плагін функціональності: він володіє транспортом викликів, інструментами, CLI, маршрутами та мостом Twilio media-stream, але споживає спільні можливості мовлення, - а також транскрибування і голосу в реальному часі, замість прямого імпорту vendor-плагінів + а також транскрипції в реальному часі і голосу в реальному часі замість прямого імпорту vendor-плагінів -Цільовий кінцевий стан такий: +Бажаний кінцевий стан: -- OpenAI знаходиться в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та +- OpenAI розміщується в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший вендор може зробити те саме для власної області поверхонь -- канали не цікавить, який саме плагін вендора володіє постачальником; вони споживають - спільний контракт можливостей, який надає core +- інший постачальник може зробити те саме для своєї власної поверхні +- канали не зважають на те, який плагін постачальника володіє провайдером; вони споживають + спільний контракт можливості, який надає ядро -Це ключова відмінність: +Ось ключова відмінність: - **plugin** = межа володіння -- **capability** = контракт core, який можуть реалізовувати або споживати кілька плагінів +- **capability** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів -Тому, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не -«який постачальник має жорстко закодувати обробку відео?» Перше запитання — «яким є -контракт core для можливості відео?» Щойно такий контракт з’являється, плагіни вендорів -можуть реєструватися для нього, а плагіни каналів/функцій — споживати його. +Тому якщо OpenClaw додає нову область, наприклад відео, перше запитання не +«який провайдер має жорстко закодувати обробку відео?» Перше запитання таке: «який +контракт можливості відео в ядрі?» Щойно такий контракт з’являється, плагіни постачальників +можуть реєструватися для нього, а плагіни каналів/функцій можуть його споживати. -Якщо можливість ще не існує, зазвичай правильний крок такий: +Якщо можливість ще не існує, правильний крок зазвичай такий: -1. визначити відсутню можливість у core -2. відкрити її через API/runtime плагінів у типізований спосіб -3. підключити канали/функції до цієї можливості -4. дати плагінам вендорів зареєструвати реалізації +1. визначити відсутню можливість у ядрі +2. відкрити її через API/середовище виконання плагінів у типізований спосіб +3. під’єднати канали/функції до цієї можливості +4. дозволити плагінам постачальників реєструвати реалізації -Це зберігає явне володіння й водночас уникає поведінки core, яка залежить від -одного вендора або одноразового специфічного шляху коду плагіна. +Це робить володіння явним і водночас уникає поведінки ядра, яка залежить від +одного постачальника або одноразового шляху коду, специфічного для плагіна. ### Шарування можливостей -Використовуйте цю ментальну модель, коли вирішуєте, де має розміщуватися код: +Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: -- **рівень можливостей core**: спільна оркестрація, політики, резервна логіка, правила - злиття конфігурації, семантика доставки та типізовані контракти -- **рівень плагіна вендора**: API вендора, автентифікація, каталоги моделей, синтез - мовлення, генерація зображень, майбутні відеобекенди, endpoints використання -- **рівень плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості core і представляє їх на певній поверхні +- **шар можливостей ядра**: спільна оркестрація, політики, резервні механізми, правила + об’єднання конфігурації, семантика доставки та типізовані контракти +- **шар плагіна постачальника**: API постачальника, автентифікація, каталоги моделей, синтез мовлення, + генерація зображень, майбутні серверні частини відео, кінцеві точки використання +- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, + яка споживає можливості ядра та відображає їх на певній поверхні Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями й доставкою в канали +- ядро володіє політикою TTS під час відповіді, порядком резервування, налаштуваннями та доставкою в канали - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний засіб runtime для TTS у телефонії +- `voice-call` споживає допоміжний засіб середовища виконання телефонного TTS -Для майбутніх можливостей слід надавати перевагу саме цьому шаблону. +Того самого шаблону слід надавати перевагу й для майбутніх можливостей. ### Приклад плагіна компанії з кількома можливостями -Плагін компанії має виглядати цілісно ззовні. Якщо в OpenClaw є спільні -контракти для моделей, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веботримання та вебпошуку, -вендор може володіти всіма своїми поверхнями в одному місці: +Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні +контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, +генерації зображень, генерації відео, отримання вебданих і вебпошуку, +постачальник може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -363,130 +353,132 @@ export default plugin; Важливі не точні назви допоміжних засобів. Важлива форма: -- один плагін володіє поверхнею вендора -- core усе ще володіє контрактами можливостей -- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора +- один плагін володіє поверхнею постачальника +- ядро, як і раніше, володіє контрактами можливостей +- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника - контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими він стверджує, що володіє ### Приклад можливості: розуміння відео OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. До неї застосовується та сама модель володіння: +можливість. Та сама модель володіння застосовується й тут: -1. core визначає контракт розуміння медіа -2. плагіни вендорів реєструють `describeImage`, `transcribeAudio` та +1. ядро визначає контракт media-understanding +2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` і `describeVideo`, де це застосовно -3. канали та плагіни функцій споживають спільну поведінку core замість - прямого підключення до коду вендора +3. канали та плагіни функцій споживають спільну поведінку ядра замість + прямого підключення до коду постачальника -Це запобігає вбудовуванню в core відеоприпущень одного постачальника. Плагін володіє -поверхнею вендора; core володіє контрактом можливості та резервною поведінкою. +Це не дає вбудувати в ядро припущення одного провайдера щодо відео. Плагін володіє +поверхнею постачальника; ядро володіє контрактом можливості та резервною поведінкою. -Генерація відео вже використовує ту саму послідовність: core володіє типізованим -контрактом можливості та допоміжним засобом runtime, а плагіни вендорів реєструють +Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим +контрактом можливості та допоміжним засобом середовища виконання, а плагіни постачальників реєструють реалізації `api.registerVideoGenerationProvider(...)` для цього контракту. -Потрібен конкретний контрольний список для впровадження? Дивіться -[Збірник рецептів для можливостей](/uk/plugins/architecture). +Потрібен конкретний контрольний список розгортання? Дивіться +[Збірник рецептів можливостей](/uk/plugins/architecture). -## Контракти та забезпечення їх дотримання +## Контракти та контроль -Поверхня API плагінів навмисно типізована й централізована в +Поверхня API плагінів навмисно типізована та централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -допоміжні засоби runtime, на які може спиратися плагін. +допоміжні засоби середовища виконання, на які може покладатися плагін. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт -- core може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють однаковий id постачальника -- під час запуску можна показувати діагностику з практичними підказками для некоректної реєстрації +- ядро може відхиляти дублювання володіння, наприклад коли два плагіни реєструють однаковий + id провайдера +- під час запуску можна показувати придатні до дії діагностичні повідомлення для хибної реєстрації - контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати тихому дрейфу -Є два рівні забезпечення дотримання: +Є два рівні контролю: -1. **забезпечення під час реєстрації в runtime** - Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Наприклад: - дубльовані id постачальників, дубльовані id постачальників мовлення та некоректні - реєстрації породжують діагностику плагіна замість невизначеної поведінки. +1. **контроль реєстрації під час виконання** + Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: + дубльовані id провайдерів, дубльовані id провайдерів мовлення та хибні + реєстрації спричиняють діагностику плагінів замість невизначеної поведінки. 2. **контрактні тести** - Вбудовані плагіни фіксуються в контрактних реєстрах під час тестових запусків, щоб - OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для модельних - постачальників, постачальників мовлення, постачальників вебпошуку та володіння + Вбудовані плагіни фіксуються в контрактних реєстрах під час виконання тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для + провайдерів моделей, провайдерів мовлення, провайдерів вебпошуку та володіння реєстрацією вбудованих плагінів. -Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою -поверхнею володіє. Це дає core і каналам змогу безшовно компонуватися, бо володіння -задеклароване, типізоване та перевірюване, а не неявне. +Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою +поверхнею володіє. Це дозволяє ядру та каналам безшовно компонуватися, адже +володіння оголошене, типізоване й придатне до перевірки, а не неявне. -### Що має належати до контракту +### Що має належати контракту Хороші контракти плагінів: - типізовані - невеликі - специфічні для можливості -- належать core -- придатні для повторного використання кількома плагінами -- можуть споживатися каналами/функціями без знання вендора +- належать ядру +- придатні до повторного використання кількома плагінами +- можуть споживатися каналами/функціями без знання постачальника Погані контракти плагінів: -- специфічна для вендора політика, прихована в core -- одноразові лазівки для плагінів, які обходять реєстр -- код каналу, що напряму звертається до реалізації вендора -- ситуативні об’єкти runtime, які не є частиною `OpenClawPluginApi` або +- політика, специфічна для постачальника, прихована в ядрі +- одноразові аварійні виходи для плагіна, які обходять реєстр +- код каналу, який напряму звертається до реалізації постачальника +- довільні об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо є сумніви, підніміть рівень абстракції: спочатку визначте можливість, а вже потім +Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а вже потім дозвольте плагінам підключатися до неї. ## Модель виконання Нативні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що -й код core. +й код ядра. Наслідки: -- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та служби -- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати її -- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw +- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси +- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати його +- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині + процесу OpenClaw -Сумісні bundle за замовчуванням безпечніші, тому що OpenClaw наразі розглядає їх -як пакети метаданих/контенту. У поточних релізах це переважно означає +Сумісні збірки безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх +як пакети метаданих/контенту. У поточних випусках це здебільшого означає вбудовані Skills. -Для невбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте -workspace-плагіни як код для часу розробки, а не як виробничі значення за замовчуванням. +Використовуйте списки дозволу та явні шляхи встановлення/завантаження для невбудованих плагінів. Розглядайте +плагіни робочого простору як код для часу розробки, а не як типовий варіант для продакшну. -Для назв пакетів вбудованого workspace зберігайте прив’язку id плагіна в назві npm: -`@openclaw/` за замовчуванням або із затвердженим типізованим суфіксом, як-от +Для назв пакетів вбудованого робочого простору тримайте id плагіна прив’язаним у npm-назві: +`@openclaw/` за замовчуванням або схвалений типізований суфікс, такий як `-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли пакет навмисно відкриває вужчу роль плагіна. -Важлива примітка щодо довіри: +Важлива примітка про довіру: - `plugins.allow` довіряє **id плагінів**, а не походженню джерела. -- Workspace-плагін із тим самим id, що й вбудований плагін, навмисно затіняє - вбудовану копію, коли цей workspace-плагін увімкнено/додано до allowlist. -- Це нормально й корисно для локальної розробки, тестування патчів і hotfix. +- Плагін робочого простору з тим самим id, що й у вбудованого плагіна, навмисно затіняє + вбудовану копію, коли цей плагін робочого простору увімкнено/додано до списку дозволу. +- Це нормально й корисно для локальної розробки, тестування патчів та термінових виправлень. ## Межа експорту OpenClaw експортує можливості, а не зручні засоби реалізації. -Зберігайте публічність реєстрації можливостей. Скорочуйте експорти допоміжних засобів, що не є контрактами: +Тримайте реєстрацію можливостей публічною. Скорочуйте експорти допоміжних засобів, які не є контрактами: -- підшляхи допоміжних засобів, специфічних для вбудованих плагінів -- підшляхи внутрішньої plumbing runtime, не призначені як публічний API -- зручні допоміжні засоби, специфічні для вендора -- допоміжні засоби setup/onboarding, які є деталями реалізації +- підшляхи допоміжних засобів, специфічні для вбудованих плагінів +- підшляхи інфраструктури середовища виконання, не призначені як публічний API +- зручні засоби, специфічні для постачальника +- допоміжні засоби налаштування/онбордингу, які є деталями реалізації -Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще лишаються в згенерованій -карті експортів SDK для сумісності та підтримки вбудованих плагінів. Поточні приклади включають +Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в згенерованій +карті експорту SDK задля сумісності та підтримки вбудованих плагінів. Поточні приклади: `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як +`plugin-sdk/zalo-setup` і кілька меж `plugin-sdk/matrix*`. Розглядайте їх як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх плагінів. @@ -495,51 +487,57 @@ OpenClaw експортує можливості, а не зручні засо Під час запуску OpenClaw приблизно робить таке: 1. виявляє корені кандидатів у плагіни -2. читає нативні або сумісні маніфести bundle та метадані пакетів +2. читає нативні маніфести або маніфести сумісних збірок і метадані пакетів 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. вирішує, чи ввімкнено кожного кандидата -6. завантажує ввімкнені нативні модулі через jiti -7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів -8. відкриває реєстр для поверхонь команд/runtime +5. вирішує питання увімкнення для кожного кандидата +6. завантажує увімкнені нативні модулі через jiti +7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів +8. відкриває реєстр для поверхонь команд/середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, який із них присутній (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання в runtime. Кандидати блокуються, -коли entry виходить за межі кореня плагіна, шлях доступний для запису всім, або -володіння шляхом виглядає підозріло для невбудованих плагінів. +Перевірки безпеки відбуваються **до** виконання коду під час виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня плагіна, шлях доступний на запис для всіх або +право власності на шлях виглядає підозрілим для невбудованих плагінів. ### Поведінка з пріоритетом маніфесту -Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для керівної площини. OpenClaw використовує його, щоб: - ідентифікувати плагін -- виявляти оголошені канали/Skills/схему конфігурації або можливості bundle -- валідовувати `plugins.entries..config` -- доповнювати мітки/заповнювачі Control UI +- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки +- перевіряти `plugins.entries..config` +- доповнювати мітки/заповнювачі в Control UI - показувати метадані встановлення/каталогу -- зберігати дешеві дескриптори активації та setup без завантаження runtime плагіна +- зберігати легкі дескриптори активації та налаштування без завантаження середовища виконання плагіна -Для нативних плагінів модуль runtime є частиною data plane. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки постачальників. +Для нативних плагінів модуль середовища виконання є частиною площини даних. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane. -Це лише дескриптори метаданих для планування активації та виявлення setup; -вони не замінюють реєстрацію runtime, `register(...)` або `setupEntry`. +Необов’язкові блоки маніфесту `activation` і `setup` залишаються в керівній площині. +Це лише дескриптори метаданих для планування активації та виявлення налаштування; +вони не замінюють реєстрацію під час виконання, `register(...)` або `setupEntry`. + +Тепер виявлення налаштування віддає перевагу id, що належать дескрипторам, таким як +`setup.providers` і `setup.cliBackends`, щоб звузити коло кандидатів у плагіни до того, як воно повернеться до +`setup-api` для плагінів, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше +ніж один виявлений плагін заявляє той самий нормалізований id провайдера налаштування або серверної частини CLI, +пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі кеші в межах процесу для: +OpenClaw підтримує короткоживучі кеші в межах процесу для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів плагінів +- реєстрів завантажених плагінів -Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно -розглядати як короткоживучі кеші продуктивності, а не як постійне сховище. +Ці кеші зменшують стрибкоподібне навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно +розглядати як короткоживучі кеші продуктивності, а не як механізм збереження стану. Примітка щодо продуктивності: @@ -550,7 +548,7 @@ OpenClaw зберігає короткоживучі кеші в межах пр ## Модель реєстру -Завантажені плагіни не змінюють напряму довільні глобальні змінні core. Вони реєструються в +Завантажені плагіни не змінюють напряму випадкові глобальні об’єкти ядра. Вони реєструються в центральному реєстрі плагінів. Реєстр відстежує: @@ -559,28 +557,27 @@ OpenClaw зберігає короткоживучі кеші в межах пр - інструменти - застарілі хуки та типізовані хуки - канали -- постачальників +- провайдерів - обробники Gateway RPC - HTTP-маршрути - реєстратори CLI -- фонові служби +- фонові сервіси - команди, що належать плагіну -Потім можливості core читають із цього реєстру, а не звертаються до модулів плагінів -напряму. Це зберігає завантаження односпрямованим: +Після цього можливості ядра читають із цього реєстру замість прямої взаємодії з модулями плагінів. +Це зберігає завантаження односпрямованим: - модуль плагіна -> реєстрація в реєстрі -- runtime core -> споживання реєстру +- середовище виконання ядра -> споживання з реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: «читати реєстр», а не «створювати спеціальний випадок для кожного модуля плагіна». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра +потрібна лише одна точка інтеграції: «читати реєстр», а не «робити окремий випадок для кожного модуля плагіна». ## Зворотні виклики прив’язки розмови -Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення отримує розв’язання. +Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку -буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримувати зворотний виклик після того, як запит на прив’язку схвалено або відхилено: ```ts export default { @@ -600,28 +597,28 @@ export default { }; ``` -Поля payload зворотного виклику: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: розв’язана прив’язка для схвалених запитів -- `request`: підсумок початкового запиту, підказка для відв’язування, id відправника та +- `binding`: визначена прив’язка для схвалених запитів +- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому -дозволено прив’язувати розмову, і виконується після завершення обробки схвалення в core. +Цей зворотний виклик є лише сповіщенням. Він не змінює того, кому дозволено прив’язувати +розмову, і виконується після завершення обробки схвалення ядром. -## Хуки runtime постачальника +## Хуки середовища виконання провайдера -Тепер плагіни постачальників мають два рівні: +Плагіни провайдерів тепер мають два шари: -- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації постачальника - до завантаження runtime, `providerAuthAliases` для варіантів постачальника, які - спільно використовують автентифікацію, `channelEnvVars` для дешевого пошуку env/setup каналу до - завантаження runtime, а також `providerAuthChoices` для дешевих міток onboarding/вибору автентифікації та - метаданих прапорців CLI до завантаження runtime +- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації провайдера + до завантаження середовища виконання, `providerAuthAliases` для варіантів провайдера, які спільно використовують + автентифікацію, `channelEnvVars` для дешевого пошуку env/налаштування каналу до + завантаження середовища виконання, а також `providerAuthChoices` для дешевих міток вибору онбордингу/автентифікації та + метаданих прапорців CLI до завантаження середовища виконання - хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- хуки runtime: `normalizeModelId`, `normalizeTransport`, +- хуки середовища виконання: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -641,90 +638,90 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw і далі володіє загальним циклом агента, failover, обробкою transcript і -політикою інструментів. Ці хуки є поверхнею розширення для специфічної поведінки постачальника без -потреби в цілком власному транспорті інференсу. +OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера поведінки без +потреби в повністю власному транспорті висновку. -Використовуйте маніфест `providerAuthEnvVars`, коли постачальник має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime плагіна. -Використовуйте маніфест `providerAuthAliases`, коли один id постачальника має повторно використовувати -env vars, auth profiles, auth на основі конфігурації та вибір onboarding API-key -іншого id постачальника. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для onboarding/вибору auth -мають знати id вибору постачальника, мітки груп і просту -однопрапорцеву прив’язку auth без завантаження runtime постачальника. Зберігайте в runtime постачальника -`envVars` для операторських підказок, таких як мітки onboarding або vars налаштування -OAuth client-id/client-secret. +Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові дані на основі env, +які загальні шляхи автентифікації/стану/вибору моделі мають бачити без завантаження середовища виконання плагіна. +Використовуйте `providerAuthAliases` у маніфесті, коли один id провайдера має повторно використовувати +env-змінні, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу API-ключа +іншого id провайдера. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI +для онбордингу/вибору автентифікації мають знати id вибору провайдера, мітки груп і просту +схему автентифікації з одним прапорцем без завантаження середовища виконання провайдера. Зберігайте +`envVars` у середовищі виконання провайдера для підказок, орієнтованих на оператора, таких як мітки онбордингу або +змінні налаштування `client-id`/`client-secret` для OAuth. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або setup, керовані env, які -загальний резервний шлях shell-env, перевірки config/status або setup prompts мають бачити -без завантаження runtime каналу. +Використовуйте `channelEnvVars` у маніфесті, коли канал має автентифікацію або налаштування, керовані env, +які загальний резервний механізм shell-env, перевірки конфігурації/стану або запити налаштування +мають бачити без завантаження середовища виконання каналу. ### Порядок хуків і використання -Для плагінів моделей/постачальників OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «When to use» — це короткий посібник для вибору. +Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий посібник для вибору. -| # | Хук | Що він робить | Коли використовувати | -| --- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або значеннями base URL за замовчуванням | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей постачальника | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається пройти звичайним шляхом реєстру/каталогу | _(це не хук плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Постачальник володіє очищенням псевдонімів перед канонічним розв’язанням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | Постачальник володіє очищенням транспорту для власних id постачальників у межах того самого сімейства транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням runtime/постачальника | Постачальнику потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підтримують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурованих постачальників | Постачальнику потрібні виправлення метаданих native streaming usage на основі endpoint | -| 7 | `resolveConfigApiKey` | Розв’язує auth з env-marker для конфігурованих постачальників до завантаження auth у runtime | Постачальник має власне розв’язання API-key з env-marker; `amazon-bedrock` також має тут вбудований AWS-розв’язувач env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі конфігурації без збереження plaintext | Постачальник може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать постачальнику; типове `persistence` — `runtime-only` для creds, що належать CLI/застосунку | Постачальник повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з auth на основі env/config | Постачальник зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний шлях для id моделей постачальника, яких ще немає в локальному реєстрі | Постачальник приймає довільні id моделей із зовнішнього джерела | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` викликається знову | Постачальнику потрібні мережеві метадані перед розв’язанням невідомих id | -| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає розв’язану модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує транспорт core | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Постачальник розпізнає власні моделі на проксі-транспортах, не перебираючи на себе володіння постачальником | -| 15 | `capabilities` | Метадані transcript/tooling, що належать постачальнику та використовуються спільною логікою core | Постачальнику потрібні особливості transcript або сімейства постачальника | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як embedded runner їх побачить | Постачальнику потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження щодо ключових слів без навчання core специфічних правил постачальника | -| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Постачальнику потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Постачальнику потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного постачальника | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Постачальнику потрібен власний wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Постачальнику потрібні обгортки сумісності заголовків/тіла/model запиту без власного транспорту | -| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані транспорту для кожного ходу | Постачальник хоче, щоб загальні транспорти надсилали native ідентичність ходу постачальника | -| 23 | `resolveWebSocketSessionPolicy` | Додає native WebSocket-заголовки або політику cool-down сесії | Постачальник хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | -| 24 | `formatApiKey` | Форматувач профілю auth: збережений профіль стає рядком `apiKey` для runtime | Постачальник зберігає додаткові метадані auth і потребує власної форми токена для runtime | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики збоїв оновлення | Постачальник не вписується в спільні засоби оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається у разі збою оновлення OAuth | Постачальнику потрібні власні вказівки з відновлення auth після збою оновлення | -| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить постачальнику | Постачальник має сирі помилки переповнення, які загальні евристики не зможуть виявити | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить постачальнику | Постачальник може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-постачальників | Постачальнику потрібне власне обмеження cache TTL для проксі | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення за відсутності auth | Постачальнику потрібна власна підказка з відновлення за відсутності auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих моделей із зовнішнього джерела плюс необов’язкова підказка про помилку для користувача | Постачальнику потрібно приховати застарілі рядки з upstream або замінити їх підказкою від вендора | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Постачальнику потрібні синтетичні рядки для прямої сумісності в `models list` і вибирачах | -| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників із binary-thinking | Постачальник підтримує лише binary thinking увімк./вимк. | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для окремих моделей | Постачальник хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для певного сімейства моделей | Постачальник володіє типовою політикою `/think` для сімейства моделей | -| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Постачальник володіє зіставленням пріоритетних моделей для live/smoke | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед інференсом | Постачальнику потрібен обмін токена або короткоживучі облікові дані для запиту | -| 38 | `resolveUsageAuth` | Розв’язує облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Постачальнику потрібен власний розбір usage/quota-токена або інші облікові дані для usage | -| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника usage/quota-знімки після розв’язання auth | Постачальнику потрібен специфічний для нього endpoint usage або парсер payload | -| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить постачальнику, для memory/search | Поведінка embedding для memory має належати плагіну постачальника | -| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для постачальника | Постачальнику потрібна власна політика transcript (наприклад, видалення thinking-block) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Постачальнику потрібні специфічні для нього переписування replay понад спільні допоміжні засоби компактування | -| 43 | `validateReplayTurns` | Остаточна валідація або переформування ходів replay перед embedded runner | Транспорту постачальника потрібна суворіша валідація ходів після загального очищення | -| 44 | `onModelSelected` | Виконує побічні дії після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або стан, що належить постачальнику, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або стандартними значеннями `base URL` | +| 2 | `applyConfigDefaults` | Застосовує глобальні стандартні значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Стандартні значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера | +| -- | _(пошук вбудованої моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(це не хук плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тій самій транспортній сім’ї | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігурації провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевими точками | +| 7 | `resolveConfigApiKey` | Визначає env-marker-автентифікацію для конфігураційних провайдерів до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований визначник AWS env-marker | +| 8 | `resolveSyntheticAuth` | Виводить локальну/self-hosted або основану на конфігурації автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; стандартне `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує облікові дані зовнішньої автентифікації без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілів порівняно з env/конфігураційною автентифікацією | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний механізм для id моделей, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей верхнього рівня | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспорті, не перехоплюючи самого провайдера | +| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскриптів/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить embedded runner | Провайдеру потрібне очищення схем для транспортної сім’ї | +| 17 | `inspectToolSchemas` | Виводить діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче отримувати попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні стандартні параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності для заголовків/тіла/моделі запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Прикріплює native-заголовки або метадані транспорту для кожного кроку | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність кроку провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | +| 24 | `formatApiKey` | Форматувальник профілю автентифікації: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані автентифікації та потребує власної форми токена під час виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилки оновлення | Провайдер не відповідає спільним засобам оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка виправлення, яка додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні вказівки щодо виправлення автентифікації після збою оновлення | +| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення вікна контексту, що належить провайдеру | Провайдер має сирі помилки переповнення, які не помітять загальні евристики | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутньої автентифікації | Провайдеру потрібна власна підказка відновлення для відсутньої автентифікації | +| 31 | `suppressBuiltInModel` | Приховування застарілих моделей верхнього рівня плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі рядки верхнього рівня або замінити їх підказкою постачальника | +| 32 | `augmentModelCatalog` | Синтетичні/підсумкові рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в `models list` і засобах вибору | +| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із двійковим thinking | Провайдер надає лише двійковий режим thinking увімк./вимк. | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | +| 35 | `resolveDefaultThinkingLevel` | Стандартний рівень `/think` для конкретного сімейства моделей | Провайдер володіє стандартною політикою `/think` для сімейства моделей | +| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед висновком | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання | +| 39 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна кінцева точка використання або аналізатор корисного навантаження, специфічні для провайдера | +| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати плагіну провайдера | +| 41 | `buildReplayPolicy` | Повертає політику повторного відтворення, що керує обробкою транскриптів для провайдера | Провайдеру потрібна власна політика транскриптів (наприклад, видалення блоків thinking) | +| 42 | `sanitizeReplayHistory` | Переписує історію повторного відтворення після загального очищення транскрипту | Провайдеру потрібні переписування повторного відтворення, специфічні для провайдера, понад спільні допоміжні засоби ущільнення | +| 43 | `validateReplayTurns` | Остаточна перевірка або переформування кроків повторного відтворення перед embedded runner | Транспорт провайдера потребує суворішої перевірки кроків після загального очищення | +| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -плагін постачальника, який збігся, а потім переходять до інших плагінів постачальників, здатних обробляти хуки, -доки один із них справді не змінить id моделі або transport/config. Це дозволяє -shim-рішенням для псевдонімів/сумісності постачальників працювати без потреби, щоб викликач знав, який -саме вбудований плагін володіє переписуванням. Якщо жоден хук постачальника не перепише підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує -це очищення сумісності. +плагін провайдера, що збігся, а потім переходять до інших плагінів провайдерів, здатних до хуків, +доки один із них фактично не змінить id моделі або транспорт/конфігурацію. Це зберігає +працездатність shim-провайдерів для псевдонімів/сумісності без вимоги до виклику знати, який +вбудований плагін володіє переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно +застосовує це очищення сумісності. -Якщо постачальнику потрібен повністю власний wire protocol або власний виконавець запитів, -це вже інший клас розширення. Ці хуки призначені для поведінки постачальника, яка все ще -працює в межах звичайного циклу інференсу OpenClaw. +Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, +це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще +працює в межах звичайного циклу висновку OpenClaw. -### Приклад постачальника +### Приклад провайдера ```ts api.registerProvider({ @@ -783,113 +780,113 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - і `wrapStreamFn`, оскільки він володіє прямою сумісністю з Claude 4.6, - підказками для сімейства постачальника, вказівками з відновлення auth, інтеграцією з - endpoint usage, правомірністю prompt-cache, значеннями конфігурації за замовчуванням з урахуванням auth, типовою/адаптивною - політикою thinking для Claude та специфічним для Anthropic формуванням потоку для + і `wrapStreamFn`, оскільки він володіє прямою сумісністю Claude 4.6, + підказками сімейства провайдера, вказівками щодо відновлення автентифікації, інтеграцією + кінцевої точки використання, придатністю prompt-cache, стандартними значеннями конфігурації з урахуванням автентифікації, стандартною/адаптивною політикою thinking + для Claude та специфічним для Anthropic формуванням потоку для beta-заголовків, `/fast` / `serviceTier` і `context1m`. -- Допоміжні засоби потоку Anthropic, специфічні для Claude, поки що залишаються у власному - публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета +- Допоміжні засоби потоку Anthropic, специфічні для Claude, наразі залишаються у + власній публічній межі `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі - конструктори обгорток Anthropic замість розширення загального SDK навколо правил beta-заголовків - одного постачальника. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі + конструктори обгорток Anthropic замість розширення загального SDK навколо правил + beta-заголовків одного провайдера. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - оскільки він володіє прямою сумісністю з GPT-5.4, прямою нормалізацією OpenAI - `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приховуванням Spark, синтетичними рядками списку OpenAI та політикою thinking / - live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє - спільними native-обгортками OpenAI Responses для заголовків attribution, - `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex, - формування payload для сумісності reasoning та керування контекстом Responses. -- OpenRouter використовує `catalog` плюс `resolveDynamicModel` і - `prepareDynamicModel`, тому що цей постачальник є pass-through і може відкривати нові + оскільки він володіє прямою сумісністю GPT-5.4, прямою нормалізацією OpenAI + `openai-completions` -> `openai-responses`, підказками автентифікації з урахуванням Codex, + приховуванням Spark, синтетичними рядками списку OpenAI і політикою GPT-5 thinking / + live-model; сімейство потоків `openai-responses-defaults` володіє + спільними native-обгортками OpenAI Responses для заголовків атрибуції, + `/fast`/`serviceTier`, деталізації тексту, native-вебпошуку Codex, + формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses. +- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і + `prepareDynamicModel`, оскільки цей провайдер є наскрізним і може відкривати нові id моделей до оновлення статичного каталогу OpenClaw; він також використовує - `capabilities`, `wrapStreamFn` та `isCacheTtlEligible`, щоб - специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і - політика prompt-cache не потрапляли в core. Його політика replay надходить із + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб утримувати + специфічні для провайдера заголовки запиту, метадані маршрутизації, патчі reasoning і + політику prompt-cache поза ядром. Його політика повторного відтворення походить із сімейства `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` - володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. + володіє ін’єкцією reasoning проксі та пропусками unsupported-model / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому - потрібні device login, що належить постачальнику, поведінка резервного вибору моделі, - особливості transcript Claude, обмін токена GitHub на токен Copilot і endpoint usage, - що належить постачальнику. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому + потрібні device login, що належать провайдеру, поведінка резервування моделі, особливості транскриптів Claude, + обмін токена GitHub на токен Copilot і кінцева точка використання, що належить провайдеру. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він - усе ще працює на core-транспортах OpenAI, але володіє своєю нормалізацією - transport/base URL, резервною політикою оновлення OAuth, типовим вибором транспорту, - синтетичними рядками каталогу Codex та інтеграцією з endpoint usage ChatGPT; він + усе ще працює на транспорті OpenAI ядра, але володіє нормалізацією свого + транспорту/`base URL`, резервною політикою оновлення OAuth, стандартним вибором транспорту, + синтетичними рядками каталогу Codex і інтеграцією кінцевої точки використання ChatGPT; він використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. - Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що - сімейство replay `google-gemini` володіє резервним шляхом прямої сумісності з Gemini 3.1, - native-валідацією replay Gemini, санітизацією bootstrap replay, режимом - tagged reasoning-output і зіставленням modern-model, тоді як - сімейство потоків `google-thinking` володіє нормалізацією payload thinking Gemini; + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки + сімейство повторного відтворення `google-gemini` володіє резервним механізмом прямої сумісності Gemini 3.1, + native-перевіркою повторного відтворення Gemini, очищенням bootstrap replay, + tagged-режимом виводу reasoning і зіставленням modern-model, тоді як + сімейство потоків `google-thinking` володіє нормалізацією payload thinking для Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токена, розбору токена та - підключення endpoint quota. + `fetchUsageSnapshot` для форматування токенів, розбору токенів і + підключення кінцевої точки квот. - Anthropic Vertex використовує `buildReplayPolicy` через - сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося + сімейство повторного відтворення `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося обмеженим id Claude, а не кожним транспортом `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що він володіє + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він володіє специфічною для Bedrock класифікацією помилок throttle/not-ready/context-overflow - для трафіку Anthropic-on-Bedrock; його політика replay все ще спільно використовує той самий - guard `anthropic-by-model`, призначений лише для Claude. + для трафіку Anthropic-on-Bedrock; його політика повторного відтворення все ще використовує той самий + захист `anthropic-by-model`, що стосується лише Claude. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, тому що вони проксують моделі Gemini - через транспорти, сумісні з OpenAI, і потребують санітизації - thought-signature Gemini без native-валідації replay Gemini або переписувань bootstrap. + через сімейство повторного відтворення `passthrough-gemini`, оскільки вони проксіюють моделі Gemini + через транспорти, сумісні з OpenAI, і потребують очищення thought-signature + Gemini без native-перевірки replay Gemini або bootstrap-переписувань. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один постачальник володіє як - семантикою Anthropic-message, так і OpenAI-compatible; він зберігає видалення - thinking-block, призначене лише для Claude, на боці Anthropic, водночас перевизначаючи режим виводу reasoning назад на native, а - сімейство потоків `minimax-fast-mode` володіє переписуванням моделей fast-mode на спільному шляху потоку. -- Moonshot використовує `catalog` плюс `wrapStreamFn`, тому що він усе ще використовує - спільний транспорт OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство потоків - `moonshot-thinking` відображає config плюс стан `/think` на його - native payload binary thinking. + сімейство повторного відтворення `hybrid-anthropic-openai`, оскільки один провайдер володіє і семантикою + повідомлень Anthropic, і семантикою, сумісною з OpenAI; він зберігає видалення + блоків thinking лише для Claude на стороні Anthropic, одночасно перевизначаючи режим виводу reasoning назад на native, а сімейство потоків `minimax-fast-mode` володіє + переписуваннями моделей fast-mode на спільному шляху потоку. +- Moonshot використовує `catalog` і `wrapStreamFn`, оскільки він усе ще використовує спільний + транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; сімейство + потоків `moonshot-thinking` відображає конфігурацію та стан `/think` на його + native-бінарний payload thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, що належать постачальнику, - нормалізація payload reasoning, підказки transcript Gemini та обмеження - cache-TTL Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію thinking Kilo - на спільному шляху proxy-потоку, пропускаючи `kilo/auto` та - інші proxy-id моделей, які не підтримують явні payload reasoning. + `isCacheTtlEligible`, оскільки йому потрібні заголовки запиту, що належать провайдеру, + нормалізація payload reasoning, підказки транскриптів Gemini та керування + TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію thinking Kilo + на спільному шляху проксі-потоку, водночас пропускаючи `kilo/auto` та + інші id проксі-моделей, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він володіє резервним шляхом GLM-5, - значеннями `tool_stream` за замовчуванням, UX binary thinking, зіставленням modern-model, а також - auth для usage і отриманням quota; сімейство потоків `tool-stream-default-on` зберігає - обгортку `tool_stream`, увімкнену за замовчуванням, поза межами рукописного glue-коду для кожного постачальника. + `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він володіє резервуванням GLM-5, + стандартними значеннями `tool_stream`, UX двійкового thinking, зіставленням modern-model + і як автентифікацією використання, так і отриманням квот; сімейство потоків `tool-stream-default-on` + утримує обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним glue-кодом + окремих провайдерів. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - тому що він володіє нормалізацією native xAI Responses transport, переписуванням - псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, - повторним використанням резервного auth для інструментів, що належать плагіну, прямим розв’язанням моделей Grok - та compat-патчами, що належать постачальнику, як-от профіль схеми інструментів xAI, - непідтримувані ключові слова схеми, native `web_search` і декодування HTML-entity - аргументів виклику інструмента. + оскільки він володіє нормалізацією native-транспорту xAI Responses, переписуванням + псевдонімів fast-mode для Grok, стандартним `tool_stream`, очищенням + strict-tool / payload reasoning, повторним використанням резервної автентифікації для інструментів, що належать плагіну, + визначенням моделей Grok із прямою сумісністю та патчами сумісності, що належать провайдеру, такими як профіль схем інструментів xAI, + непідтримувані ключові слова схеми, native `web_search` і декодування аргументів + виклику інструментів у HTML-сутностях. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - особливості transcript/tooling не потрапляли в core. -- Вбудовані постачальники лише з каталогом, як-от `byteplus`, `cloudflare-ai-gateway`, + винести особливості транскриптів/інструментів за межі ядра. +- Вбудовані провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації - розуміння медіа і генерації відео для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, оскільки їхня поведінка `/usage` - належить плагіну, хоча сам інференс усе ще працює через спільні транспорти. +- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації + media-understanding і video-generation для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog`, а також хуки використання, оскільки їхня поведінка `/usage` + належить плагіну, навіть якщо висновок усе ще проходить через спільні транспорти. -## Допоміжні засоби runtime +## Допоміжні засоби середовища виконання -Плагіни можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -910,14 +907,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload виводу TTS із core для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію core `messages.tts` і вибір постачальника. -- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни мають виконувати ресемплінг/кодування для постачальників. -- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для вибирачів голосів або потоків setup, що належать вендору. -- Списки голосів можуть включати багатші метадані, такі як локаль, стать і теги особистості для вибирачів з урахуванням постачальника. +- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію `messages.tts` ядра та вибір провайдера. +- Повертає буфер аудіо PCM + частоту дискретизації. Плагіни мають виконувати повторну дискретизацію/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику. +- Списки голосів можуть містити розширені метадані, такі як локаль, стать і теги характеру для засобів вибору з урахуванням провайдера. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -937,15 +934,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, резервний вибір і доставку відповідей у core. -- Використовуйте постачальників мовлення для поведінки синтезу, що належить вендору. -- Застарілий вхід Microsoft `edge` нормалізується до id постачальника `microsoft`. -- Бажана модель володіння орієнтована на компанію: один плагін вендора може володіти - постачальниками тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додає +- Зберігайте політику TTS, резервування та доставку відповідей у ядрі. +- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику. +- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один плагін постачальника може володіти + текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додає ці контракти можливостей. -Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого -постачальника розуміння медіа замість загального key/value-набору: +Для розуміння зображень/аудіо/відео плагіни реєструють один типізований +провайдер media-understanding замість загального набору key/value: ```ts api.registerMediaUnderstandingProvider({ @@ -959,16 +956,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, резервний вибір, конфігурацію та підключення каналів у core. -- Зберігайте поведінку вендора в плагіні постачальника. -- Розширення шляхом додавання має залишатися типізованим: нові необов’язкові методи, нові необов’язкові +- Зберігайте оркестрацію, резервні механізми, конфігурацію та підключення каналів у ядрі. +- Зберігайте поведінку постачальника в плагіні провайдера. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та допоміжним засобом runtime - - плагіни вендорів реєструють `api.registerVideoGenerationProvider(...)` + - ядро володіє контрактом можливості та допоміжним засобом середовища виконання + - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)` - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів runtime розуміння медіа плагіни можуть викликати: +Для допоміжних засобів середовища виконання media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -983,8 +980,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо плагіни можуть використовувати або runtime -розуміння медіа, або старіший псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або середовище виконання media-understanding, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -997,13 +994,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` — це пріоритетна спільна поверхня для +- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо розуміння медіа з core (`tools.media.audio`) і порядок резервного вибору постачальників. -- Повертає `{ text: undefined }`, коли результат транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу). +- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок резервування провайдерів. +- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу). - `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. -Плагіни також можуть запускати фонові запуски subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові виконання підлеглих агентів через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1018,13 +1015,13 @@ const result = await api.runtime.subagent.run({ Примітки: - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. -- OpenClaw враховує ці поля перевизначення лише для довірених викликачів. +- OpenClaw враховує ці поля перевизначення лише для довірених викликів. - Для резервних запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. - Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски subagent із недовірених плагінів теж працюють, але запити на перевизначення відхиляються замість тихого переходу на резервний варіант. +- Запуски підлеглих агентів із недовірених плагінів також працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного варіанта. -Для вебпошуку плагіни можуть використовувати спільний допоміжний засіб runtime замість -прямого доступу до підключення інструмента агента: +Для вебпошуку плагіни можуть споживати спільний допоміжний засіб середовища виконання замість +звернення до підключення інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1040,14 +1037,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати постачальників вебпошуку через +Плагіни також можуть реєструвати провайдерів вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у core. -- Використовуйте постачальників вебпошуку для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це пріоритетна спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1062,12 +1059,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка постачальників генерації зображень. -- `listProviders(...)`: перелічує доступних постачальників генерації зображень і їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: виводить список доступних провайдерів генерації зображень та їхніх можливостей. ## HTTP-маршрути Gateway -Плагіни можуть відкривати HTTP-endpoint через `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP-кінцеві точки через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1084,24 +1081,24 @@ api.registerHttpRoute({ Поля маршруту: -- `path`: шлях маршруту в HTTP-сервері gateway. -- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує плагін. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки вебхуків, якими керує плагін. +- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому плагіну замінювати власну наявну реєстрацію маршруту. - `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Замість нього використовуйте `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. - Маршрути плагінів мають явно оголошувати `auth`. - Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише в межах одного рівня `auth`. -- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/перевірки підписів, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах області runtime запиту Gateway, але ця область навмисно консервативна: - - bearer-auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з передаванням ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з передаванням ідентичності, область runtime повертається до `operator.write` -- Практичне правило: не вважайте маршрут плагіна з auth gateway неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth із передаванням ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюги переходу `exact`/`prefix` лише в межах одного рівня auth. +- Маршрути з `auth: "plugin"` **не** отримують автоматично операторські області середовища виконання. Вони призначені для вебхуків/перевірки підписів, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. +- Маршрути з `auth: "gateway"` працюють усередині області середовища виконання запиту Gateway, але ця область навмисно консервативна: + - bearer-автентифікація через спільний секрет (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршруту плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з носієм ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з носієм ідентичності, область середовища виконання повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут плагіна з автентифікацією gateway автоматично є поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з носієм ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK @@ -1109,7 +1106,7 @@ api.registerHttpRoute({ - `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. - `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. -- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` +- `openclaw/plugin-sdk/config-schema` для експорту кореневої схеми Zod `openclaw.json` (`OpenClawSchema`). - Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1123,18 +1120,18 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного підключення setup/auth/reply/webhook. - `channel-inbound` — це спільний дім для debounce, зіставлення згадок, - допоміжних засобів політики вхідних згадок, форматування envelope і - допоміжних засобів контексту вхідного envelope. - `channel-setup` — це вузький шов setup для необов’язкового встановлення. - `setup-runtime` — це безпечна для runtime поверхня setup, що використовується `setupEntry` / - відкладеним запуском, включно з безпечними для імпорту адаптерами patch setup. - `setup-adapter-runtime` — це env-aware шов адаптера налаштування облікового запису. - `setup-tools` — це малий шов допоміжних засобів CLI/архівів/документації (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` для спільного підключення + налаштування/автентифікації/відповідей/вебхуків. `channel-inbound` — це спільне місце для debounce, зіставлення згадок, + допоміжних засобів політики вхідних згадок, форматування конвертів і допоміжних засобів + контексту вхідних конвертів. + `channel-setup` — це вузька межа налаштування для необов’язкового встановлення. + `setup-runtime` — це безпечна для середовища виконання поверхня налаштування, яку використовують `setupEntry` / + відкладений запуск, включно з безпечними для імпорту адаптерами патчів налаштування. + `setup-adapter-runtime` — це межа адаптера налаштування облікового запису з урахуванням env. + `setup-tools` — це мала межа допоміжних засобів для CLI/архівів/документації (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Предметні підшляхи, як-от `openclaw/plugin-sdk/channel-config-helpers`, +- Підшляхи доменів, такі як `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1152,194 +1149,191 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config. - `telegram-command-config` — це вузький публічний шов для нормалізації/валідації власних - команд Telegram і залишається доступним навіть якщо поверхня контракту вбудованого + `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів середовища виконання/конфігурації. + `telegram-command-config` — це вузька публічна межа для нормалізації/валідації користувацьких + команд Telegram і залишається доступною навіть якщо поверхня контракту вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний шов text/markdown/logging, включно з - видаленням тексту, видимого асистенту, допоміжними засобами рендерингу/чанкування markdown, засобами редагування - та безпечними текстовими утилітами. -- Для специфічних для схвалення швів каналів слід надавати перевагу одному контракту `approvalCapability` - на плагіні. Потім core читає auth, доставку, рендеринг, - native-routing і ледачу поведінку native-handler для схвалення через цю одну можливість - замість змішування поведінки схвалення з не пов’язаними полями плагіна. + `text-runtime` — це спільна межа тексту/markdown/логування, включно з + видаленням тексту, видимого асистенту, допоміжними засобами рендерингу/розбиття markdown, допоміжними засобами редагування, + допоміжними засобами тегів директив і утилітами безпечного тексту. +- Для меж каналів, специфічних для погодження, слід надавати перевагу одному контракту + `approvalCapability` на плагіні. Тоді ядро читає auth, доставку, рендеринг, + native-routing і поведінку lazy native-handler для погодження через одну цю можливість + замість змішування поведінки погодження з не пов’язаними полями плагіна. - `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як shim сумісності для старіших плагінів. Новий код має імпортувати вужчі загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього shim. -- Внутрішні частини вбудованих розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може використовувати - публічні точки входу репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js`, а також вузько спрямовані файли, такі як - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з +- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише + підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати + публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` і вузькоспрямовані файли, наприклад + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з іншого розширення. -- Поділ точки входу репозиторію: - `/api.js` — це barrel допоміжних засобів/типів, - `/runtime-api.js` — це barrel лише для runtime, +- Розділення точок входу репозиторію: + `/api.js` — це барель допоміжних засобів/типів, + `/runtime-api.js` — це барель лише для середовища виконання, `/index.js` — це точка входу вбудованого плагіна, - а `/setup-entry.js` — це точка входу setup-плагіна. -- Поточні приклади вбудованих постачальників: + а `/setup-entry.js` — це точка входу плагіна налаштування. +- Поточні приклади вбудованих провайдерів: - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких - як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`. - - OpenAI використовує `api.js` для конструкторів постачальників, допоміжних засобів типової моделі та - конструкторів постачальників realtime. - - OpenRouter використовує `api.js` для свого конструктора постачальника плюс допоміжних засобів - onboarding/config, тоді як `register.runtime.js` і далі може повторно експортувати загальні + як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і розбір `service_tier`. + - OpenAI використовує `api.js` для конструкторів провайдера, допоміжних засобів стандартних моделей і + конструкторів провайдерів реального часу. + - OpenRouter використовує `api.js` для свого конструктора провайдера та допоміжних засобів + онбордингу/конфігурації, тоді як `register.runtime.js` усе ще може повторно експортувати загальні допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime, - якщо він існує, а тоді повертаються до розв’язаного файлу конфігурації на диску, коли - OpenClaw ще не надає знімок runtime. -- Загальні спільні примітиви залишаються пріоритетним публічним контрактом SDK. Невеликий - зарезервований сумісний набір branded helper-швів вбудованих каналів усе ще існує. Розглядайте їх як - шви для підтримки вбудованих рішень/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти й далі мають з’являтися в - загальних підшляхах `plugin-sdk/*` або в локальних barrel `api.js` / - `runtime-api.js` плагіна. +- Публічні точки входу, завантажені через фасад, віддають перевагу активному знімку конфігурації середовища виконання, + якщо він існує, а потім повертаються до визначеного файла конфігурації на диску, коли + OpenClaw ще не обслуговує знімок середовища виконання. +- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір меж допоміжних засобів із брендингом вбудованих каналів усе ще існує. Розглядайте їх як межі для підтримки вбудованих компонентів/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти й надалі мають потрапляти до + загальних підшляхів `plugin-sdk/*` або до локальних барелів плагіна `api.js` / + `runtime-api.js`. Примітка щодо сумісності: -- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. +- Уникайте кореневого бареля `openclaw/plugin-sdk` у новому коді. - Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це цільовий контракт для нової роботи з + allowlist/status/message-tool є бажаним контрактом для нової роботи з вбудованими та зовнішніми плагінами. Розбір/зіставлення цілей має розміщуватися в `openclaw/plugin-sdk/channel-targets`. - Обмеження дій повідомлень і допоміжні засоби message-id для реакцій мають розміщуватися в + Обмеження дій повідомлень і допоміжні засоби для id повідомлень реакцій мають розміщуватися в `openclaw/plugin-sdk/channel-actions`. -- Barrel-модулі допоміжних засобів, специфічні для вбудованих розширень, за замовчуванням не є стабільними. Якщо - допоміжний засіб потрібен лише вбудованому розширенню, залишайте його за локальним - швом `api.js` або `runtime-api.js` цього розширення замість просування в +- Барелі допоміжних засобів, специфічні для вбудованих розширень, не є стабільними за замовчуванням. Якщо + допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальною + межею `api.js` або `runtime-api.js` цього розширення замість просування його до `openclaw/plugin-sdk/`. -- Нові спільні шви допоміжних засобів мають бути загальними, а не брендованими під конкретний канал. Спільний розбір - цілей має розміщуватися в `openclaw/plugin-sdk/channel-targets`; внутрішні частини, специфічні для каналу, - мають залишатися за локальним швом `api.js` або `runtime-api.js` - плагіна-власника. +- Нові спільні межі допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір + цілей має належати `openclaw/plugin-sdk/channel-targets`; внутрішні компоненти, специфічні для каналу, + мають залишатися за локальною межею `api.js` або `runtime-api.js` плагіна-власника. - Підшляхи, специфічні для можливостей, такі як `image-generation`, - `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують - їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є - довгостроковим зафіксованим зовнішнім контрактом. + `media-understanding` і `speech`, існують, оскільки вбудовані/нативні плагіни використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є + довгостроковим замороженим зовнішнім контрактом. ## Схеми інструмента повідомлень -Плагіни мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. -Зберігайте поля, специфічні для постачальника, у плагіні, а не в спільному core. +Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу. +Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному ядрі. -Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через -`openclaw/plugin-sdk/channel-actions`: +Для спільних переносимих фрагментів схеми повторно використовуйте загальні допоміжні засоби, +експортовані через `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок - `createMessageToolCardSchema()` для payload структурованих карток -Якщо форма схеми має сенс лише для одного постачальника, визначайте її у власному -коді цього плагіна замість просування до спільного SDK. +Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному +вихідному коді цього плагіна замість просування до спільного SDK. -## Розв’язання цілей каналу +## Визначення цілей каналу -Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -outbound host загальним і використовуйте поверхню адаптера повідомлень для правил постачальника: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Тримайте спільний +вихідний хост загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль - слід трактувати як `direct`, `group` або `channel` до пошуку в директорії. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - вхідні дані слід одразу спрямувати до розв’язання за схожістю з id, а не до пошуку в директорії. -- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях плагіна, коли - core потребує фінального розв’язання, що належить постачальнику, після нормалізації або - після пропуску в директорії. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту outbound-сесії, - специфічною для постачальника, щойно ціль розв’язано. +- `messaging.inferTargetChatType({ to })` визначає, чи слід трактувати нормалізовану ціль + як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи + слід для вводу одразу перейти до визначення за схожістю з id замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` — це резервний механізм плагіна, коли + ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або + після промаху пошуку в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, специфічною для провайдера, + після того як ціль визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до - пошуку серед peer/group. -- Використовуйте `looksLikeId` для перевірок типу «обробляти це як явний/native id цілі». -- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для постачальника, а не для - широкого пошуку в директорії. -- Зберігайте native id постачальника, такі як id чатів, id тредів, JID, handles та id кімнат, - усередині значень `target` або параметрів, специфічних для постачальника, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися до + пошуку серед співрозмовників/груп. +- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/native id цілі». +- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для + широкого пошуку в каталозі. +- Тримайте native id провайдера, такі як chat id, thread id, JID, handles і room + ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Директорії на основі конфігурації +## Каталоги на основі конфігурації -Плагіни, які виводять записи директорії з конфігурації, мають зберігати цю логіку в +Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні каталоги співрозмовників/груп на основі конфігурації, такі як: -- DM-peer на основі allowlist -- налаштовані мапи каналів/груп -- статичні резервні варіанти директорії в межах облікового запису +- DM-співрозмовники, керовані списком дозволу +- налаштовані відображення каналів/груп +- статичні резервні варіанти каталогу в межах облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: - фільтрацію запитів - застосування обмежень -- видалення дублікатів/нормалізацію +- допоміжні засоби усунення дублікатів/нормалізації - побудову `ChannelDirectoryEntry[]` -Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися в -реалізації плагіна. +Інспекція облікових записів і нормалізація id, специфічні для каналу, мають залишатися +в реалізації плагіна. -## Каталоги постачальників +## Каталоги провайдерів -Плагіни постачальників можуть визначати каталоги моделей для інференсу через +Плагіни провайдерів можуть визначати каталоги моделей для висновку через `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: -- `{ provider }` для одного запису постачальника -- `{ providers }` для кількох записів постачальників +- `{ provider }` для одного запису провайдера +- `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли плагін володіє специфічними для постачальника id моделей, значеннями base URL -за замовчуванням або метаданими моделей, закритими auth. +Використовуйте `catalog`, коли плагін володіє id моделей, специфічними для провайдера, стандартними значеннями base URL або метаданими моделей, обмеженими автентифікацією. -`catalog.order` керує тим, коли каталог плагіна зливається відносно -вбудованих неявних постачальників OpenClaw: +`catalog.order` контролює, коли каталог плагіна об’єднується відносно +вбудованих неявних провайдерів OpenClaw: -- `simple`: звичайні постачальники на основі API-key або env -- `profile`: постачальники, які з’являються, коли існують профілі auth -- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників -- `late`: останній прохід, після інших неявних постачальників +- `simple`: звичайні провайдери з API-ключем або керовані env +- `profile`: провайдери, які з’являються, коли існують профілі автентифікації +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера +- `late`: останній прохід, після інших неявних провайдерів -Пізніші постачальники перемагають у разі конфлікту ключів, тож плагіни можуть навмисно -перевизначати вбудований запис постачальника з тим самим id постачальника. +Пізніші провайдери перемагають у разі колізії ключів, тому плагіни можуть навмисно +перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` і далі працює як застарілий псевдонім +- `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` ## Інспекція каналу лише для читання -Якщо ваш плагін реєструє канал, краще реалізувати -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш плагін реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. +- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися з помилкою, коли бракує потрібних секретів. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` і потоки - doctor/config repair не повинні потребувати матеріалізації runtime-облікових даних лише для - опису конфігурації. + `openclaw channels status`, `openclaw channels resolve` і потоки виправлення doctor/config, + не повинні потребувати матеріалізації облікових даних середовища виконання лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: -- Повертає лише описовий стан облікового запису. -- Зберігає `enabled` і `configured`. -- За потреби включає поля джерела/стану облікових даних, наприклад: +- Повертайте лише описовий стан облікового запису. +- Зберігайте `enabled` і `configured`. +- Додавайте поля джерела/статусу облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі тільки читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. -## Package packs +## Набори пакетів -Директорія плагіна може містити `package.json` з `openclaw.extensions`: +Каталог плагіна може містити `package.json` з `openclaw.extensions`: ```json { @@ -1351,64 +1345,63 @@ outbound host загальним і використовуйте поверхн } ``` -Кожен запис стає плагіном. Якщо pack містить кілька розширень, id плагіна +Кожен запис стає плагіном. Якщо набір перелічує кілька розширень, id плагіна стає `name/`. -Якщо ваш плагін імпортує npm-залежності, установіть їх у цій директорії, щоб +Якщо ваш плагін імпортує npm-залежності, встановіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Запобіжний захід безпеки: кожен запис `openclaw.extensions` має залишатися в межах директорії плагіна -після розв’язання symlink. Записи, які виходять за межі директорії пакета, -відхиляються. +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу плагіна +після визначення символьних посилань. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Зберігайте дерева залежностей плагінів «чистими JS/TS» і уникайте пакетів, які потребують `postinstall`-збірок. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей під час виконання). Тримайте дерева залежностей плагіна «чистими JS/TS» і уникайте пакетів, які потребують збирання через `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або -коли плагін каналу ввімкнено, але він іще не налаштований, OpenClaw завантажує `setupEntry` -замість повної точки входу плагіна. Це робить запуск і setup легшими, -коли головна точка входу плагіна також підключає інструменти, хуки або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого плагіна каналу, або +коли плагін каналу увімкнено, але він усе ще не налаштований, він завантажує `setupEntry` +замість повної точки входу плагіна. Це зберігає запуск і налаштування легшими, +коли ваша основна точка входу плагіна також підключає інструменти, хуки або інший код, +призначений лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести плагін каналу на той самий шлях `setupEntry` під час -передпрослуховувальної фази запуску gateway, навіть коли канал уже налаштовано. +може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску gateway +до початку прослуховування, навіть коли канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup -має зареєструвати кожну можливість, що належить каналу й від якої залежить запуск, зокрема: +до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування +має зареєструвати всі можливості, що належать каналу та від яких залежить запуск, зокрема: - саму реєстрацію каналу - будь-які HTTP-маршрути, які мають бути доступні до початку прослуховування gateway -- будь-які методи gateway, інструменти або служби, які мають існувати в тому самому вікні +- будь-які методи gateway, інструменти або сервіси, які мають існувати протягом цього самого вікна -Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште для плагіна типову поведінку й дозвольте OpenClaw завантажити +Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте +цей прапорець. Залишайте плагін на стандартній поведінці та дозвольте OpenClaw завантажити повну точку входу під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, які core -може використовувати до завантаження повного runtime каналу. Поточна поверхня -просування setup така: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро +може консультуватися до завантаження повного середовища виконання каналу. Поточна поверхня +просування налаштування така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до +Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повної точки входу плагіна. -Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap до -іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ типового облікового запису замість того, щоб завжди створювати +Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap у +іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може +зберігати налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери patch setup зберігають ледаче виявлення поверхні контракту вбудованих рішень. Час -імпорту залишається малим; поверхня просування завантажується лише під час першого використання, а не -повторно входить у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають ледаче виявлення поверхні контракту вбудованих компонентів. Час +імпорту залишається малим; поверхня просування завантажується лише під час першого використання, а не через повторний вхід у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх на -специфічному для плагіна префіксі. Простори імен адміністратора core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються -до `operator.admin`, навіть якщо плагін запитує вужчу область. +Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на +префіксі, специфічному для плагіна. Простори імен адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими та завжди визначаються +як `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -1427,8 +1420,8 @@ Core використовує цю поверхню, коли потрібно ### Метадані каталогу каналів -Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel`, а -підказки щодо встановлення — через `openclaw.install`. Це дозволяє core не містити даних каталогу. +Плагіни каналів можуть рекламувати метадані налаштування/виявлення через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. Приклад: @@ -1443,7 +1436,7 @@ Core використовує цю поверхню, коли потрібно "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", + "blurb": "Самостійно розгорнутий чат через ботів вебхуків Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1459,38 +1452,38 @@ Core використовує цю поверхню, коли потрібно Корисні поля `openclaw.channel` понад мінімальний приклад: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначає текст посилання на документацію +- `docsLabel`: перевизначення тексту посилання для посилання на документацію - `preferOver`: id плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору -- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо outbound-форматування +- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних вибирачів setup/configure, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; краще використовувати `exposure` -- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час розв’язання цілей оголошення +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` +- `quickstartAllowFrom`: додає канал до стандартного потоку `allowFrom` для швидкого старту +- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей оголошення -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). -Помістіть JSON-файл в одне з таких місць: +OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Помістіть JSON-файл в одне з таких місць: - `~/.openclaw/mpm/plugins.json` - `~/.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"`. +один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Аналізатор також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Плагіни контекстного рушія +## Плагіни механізму контексту -Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly -та compaction. Реєструйте їх із вашого плагіна через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через +Плагіни механізму контексту володіють оркестрацією контексту сесії для поглинання, збирання +та ущільнення. Реєструйте їх із вашого плагіна через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати memory search або хуки. +Використовуйте це, коли вашому плагіну потрібно замінити або розширити стандартний +конвеєр контексту, а не просто додати пошук у пам’яті або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1518,7 +1511,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом compaction, залиште `compact()` +Якщо ваш механізм **не** володіє алгоритмом ущільнення, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1557,40 +1550,40 @@ export default function (api) { ## Додавання нової можливості Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний доступ до внутрішніх частин. Додайте відсутню можливість. +систему плагінів через приватне проникнення всередину. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політика, резервний вибір, злиття конфігурації, - життєвий цикл, семантика для каналів і форма допоміжного засобу runtime. -2. додайте типізовані поверхні реєстрації/runtime плагіна +1. визначте контракт ядра + Вирішіть, якою спільною поведінкою має володіти ядро: політика, резервні механізми, об’єднання конфігурації, + життєвий цикл, семантика, орієнтована на канали, і форма допоміжних засобів середовища виконання. +2. додайте типізовані поверхні реєстрації/середовища виконання плагінів Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть споживачів core + каналів/функцій - Канали та плагіни функцій мають споживати нову можливість через core, - а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендорів - Потім плагіни вендорів реєструють свої бекенди для цієї можливості. +3. під’єднайте споживачів ядра + каналів/функцій + Канали та плагіни функцій мають споживати нову можливість через ядро, + а не шляхом прямого імпорту реалізації постачальника. +4. зареєструйте реалізації постачальників + Потім плагіни постачальників реєструють свої серверні частини для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається концептуально цілісним, не стаючи жорстко прив’язаним до -бачення одного постачальника. Дивіться [Збірник рецептів для можливостей](/uk/plugins/architecture), -щоб побачити конкретний контрольний список файлів і опрацьований приклад. +Саме так OpenClaw зберігає визначеність, не стаючи жорстко прив’язаним до +світогляду одного провайдера. Дивіться [Збірник рецептів можливостей](/uk/plugins/architecture) +для конкретного контрольного списку файлів і готового прикладу. -### Контрольний список можливості +### Контрольний список можливостей -Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких -поверхонь: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: -- типи контрактів core у `src//types.ts` -- helper runner/runtime у core в `src//runtime.ts` +- типи контракту ядра в `src//types.ts` +- засіб виконання/допоміжний засіб ядра в `src//runtime.ts` - поверхня реєстрації API плагінів у `src/plugins/types.ts` - підключення реєстру плагінів у `src/plugins/registry.ts` -- відкриття runtime плагінів у `src/plugins/runtime/*`, коли плагінам функцій/каналів - потрібно це споживати -- helper для capture/test у `src/test-utils/plugin-registration.ts` +- відкриття середовища виконання плагінів у `src/plugins/runtime/*`, коли плагіни функцій/каналів + мають це споживати +- допоміжні засоби захоплення/тестування в `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` - документація для операторів/плагінів у `docs/` @@ -1633,7 +1626,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- core володіє контрактом можливості + оркестрацією -- плагіни вендорів володіють реалізаціями вендорів -- плагіни функцій/каналів споживають допоміжні засоби runtime -- контрактні тести зберігають явність володіння +- ядро володіє контрактом можливості + оркестрацією +- плагіни постачальників володіють реалізаціями постачальників +- плагіни функцій/каналів споживають допоміжні засоби середовища виконання +- контрактні тести зберігають володіння явним diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 502434769..a253ce2e5 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -2,13 +2,13 @@ read_when: - Ви створюєте плагін OpenClaw - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна -summary: Маніфест плагіна + вимоги до JSON schema (сувора валідація конфігурації) +summary: Вимоги до маніфесту плагіна + JSON schema (сувора валідація конфігурації) title: Маніфест плагіна x-i18n: - generated_at: "2026-04-11T11:37:24Z" + generated_at: "2026-04-12T02:30:56Z" model: gpt-5.4 provider: openai - source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 + source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91 source_path: plugins/manifest.md workflow: 15 --- @@ -17,35 +17,35 @@ x-i18n: Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**. -Сумісні макети пакетів описано в [Пакети плагінів](/uk/plugins/bundles). +Сумісні макети пакунків описано в [Пакунки плагінів](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати пакунків використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude +- Пакунок Codex: `.codex-plugin/plugin.json` +- Пакунок Claude: `.claude-plugin/plugin.json` або типовий макет компонентів Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- Пакунок Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію +OpenClaw також автоматично виявляє ці макети пакунків, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені -кореневі каталоги Skills, кореневі каталоги команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude та підтримувані набори хуків, якщо макет відповідає +Для сумісних пакунків OpenClaw наразі зчитує метадані пакунка, а також оголошені +кореневі каталоги skill, кореневі каталоги команд Claude, типові значення `settings.json` у пакунку Claude, +типові значення LSP у пакунку Claude та підтримувані набори hooks, якщо макет відповідає очікуванням середовища виконання OpenClaw. -Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у +Кожен власний плагін OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються -помилками плагіна і блокують валідацію конфігурації. +помилками плагіна та блокують валідацію конфігурації. -Повний посібник із системи плагінів див. у [Плагіни](/uk/tools/plugin). -Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +Дивіться повний посібник із системи плагінів: [Плагіни](/uk/tools/plugin). +Щодо власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). -## Для чого потрібен цей файл +## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду вашого плагіна. Використовуйте його для: @@ -54,27 +54,25 @@ OpenClaw також автоматично виявляє ці макети па - валідації конфігурації - метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна -- легких підказок активації, які поверхні control-plane можуть перевіряти до - завантаження середовища виконання -- легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до - завантаження середовища виконання -- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження - середовища виконання плагіна -- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати - плагін до завантаження середовища виконання -- статичних знімків належності можливостей, що використовуються для сумісної обв’язки - bundled-плагінів і покриття контрактів -- метаданих конфігурації каналу, специфічних для каналу, які мають зливатися в поверхні - каталогу та валідації без завантаження середовища виконання +- легковагих підказок активації, які поверхні control plane можуть перевіряти до завантаження runtime +- легковагих дескрипторів налаштування, які поверхні setup/onboarding можуть перевіряти до завантаження + runtime +- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження runtime плагіна +- скорочених метаданих належності до сімейств моделей, які мають автоматично активувати + плагін до завантаження runtime +- статичних знімків належності можливостей, які використовуються для bundled compat wiring і + покриття контрактів +- метаданих конфігурації каналу, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації + без завантаження runtime - підказок UI для конфігурації Не використовуйте його для: -- реєстрації поведінки під час виконання -- оголошення кодових entrypoint +- реєстрації поведінки runtime +- оголошення entrypoint коду - метаданих встановлення npm -Це належить до коду вашого плагіна та `package.json`. +Це належить вашому коду плагіна та `package.json`. ## Мінімальний приклад @@ -145,64 +143,64 @@ OpenClaw також автоматично виявляє ці макети па } ``` -## Довідка щодо полів верхнього рівня +## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що це означає | +| Поле | Обов’язкове | Тип | Що воно означає | | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Так | `string` | Канонічний id плагіна. Це id, який використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. | -| `enabledByDefault` | Ні | `true` | Позначає bundled-плагін як увімкнений типово. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим типово. | +| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. | | `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id плагіна. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує винятковий вид плагіна, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли на них посилаються auth, config або model refs. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип плагіна, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Id каналів, якими володіє цей плагін. Використовуються для виявлення та валідації конфігурації. | | `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей плагін. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження плагіна до середовища виконання. | -| `cliBackends` | Ні | `string[]` | Id backend у CLI, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін, що мають створювати діагностику конфігурації й CLI з урахуванням плагіна до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Легкі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | -| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад coding-провайдер, що ділить API key і профілі автентифікації з базовим провайдером. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити типові помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для picker онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Легкі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка як і раніше належить середовищу виконання плагіна. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання плагіна. | -| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності інструментів. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест, що зливаються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження відносно кореня плагіна. | -| `name` | Ні | `string` | Зручна для читання назва плагіна. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. | -| `version` | Ні | `string` | Інформаційна версія плагіна. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки чутливості для полів конфігурації. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, якими володіє маніфест, що використовуються для автоматичного завантаження плагіна до runtime. | +| `cliBackends` | Ні | `string[]` | Id backend для висновування в CLI, якими володіє цей плагін. Використовуються для автоматичної активації під час запуску з явних посилань у config. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін, і які мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Легковагі метадані env для auth провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | +| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку auth, наприклад coding provider, що спільно використовує API key базового провайдера та профілі auth. | +| `channelEnvVars` | Ні | `Record` | Легковагі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь auth, які мають бачити загальні helpers запуску/config. | +| `providerAuthChoices` | Ні | `object[]` | Легковагі метадані вибору auth для picker-ів онбордингу, визначення preferred provider і простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легковагі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою як і раніше володіє runtime плагіна. | +| `setup` | Ні | `object` | Легковагі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime плагіна. | +| `contracts` | Ні | `object` | Статичний знімок bundled capability для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tool. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | +| `name` | Ні | `string` | Людинозрозуміла назва плагіна. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. | +| `version` | Ні | `string` | Інформаційна версія плагіна. | +| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. | -## Довідка щодо `providerAuthChoices` +## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw читає це до завантаження середовища виконання провайдера. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth. +OpenClaw зчитує це до завантаження runtime провайдера. -| Поле | Обов’язкове | Тип | Що це означає | -| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати запит. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в онбордингу та потоках CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker асистента, але все одно дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Id методу auth, до якого слід диспетчеризувати. | +| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується в потоках онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker-а. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker-ах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker-ів асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | +| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, використовується `["text-inference"]`. | -## Довідка щодо `commandAliases` +## Довідник `commandAliases` Використовуйте `commandAliases`, коли плагін володіє назвою runtime-команди, яку користувачі можуть помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна. +використовує ці метадані для діагностики без імпорту коду runtime плагіна. ```json { @@ -216,19 +214,19 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | -| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід рекомендувати для операцій CLI, якщо вона існує. | -## Довідка щодо `activation` +## Довідник `activation` -Використовуйте `activation`, коли плагін може дешево оголосити, які події control-plane +Використовуйте `activation`, коли плагін може дешево оголосити, які події control plane мають активувати його пізніше. -Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і -не замінює `register(...)`, `setupEntry` чи інші entrypoint runtime/плагіна. +Цей блок містить лише метадані. Він не реєструє поведінку runtime і не +замінює `register(...)`, `setupEntry` або інші runtime/plugin entrypoint-и. ```json { @@ -242,18 +240,18 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ | -| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей плагін за запитом. | -| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей плагін. | -| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей плагін. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають активувати цей плагін. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control-plane. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей плагін за запитом. | +| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей плагін. | +| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей плагін. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються в плануванні активації control plane. | -## Довідка щодо `setup` +## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, якими володіє плагін, -до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві метадані, +якими володіє плагін, до завантаження runtime. ```json { @@ -272,30 +270,40 @@ OpenClaw читає це до завантаження середовища ви } ``` -Поле верхнього рівня `cliBackends` залишається валідним і надалі описує backend інференсу CLI. -`setup.cliBackends` — це поверхня дескриптора, специфічна для налаштування, -для потоків control-plane/налаштування, яка має залишатися лише метаданими. +`cliBackends` верхнього рівня залишається валідним і надалі описує backend-и +висновування CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, +для потоків control plane/setup, яка має залишатися лише метаданими. -### Довідка щодо `setup.providers` +Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною +поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор лише +звужує коло плагінів-кандидатів, а setup все ще потребує багатших runtime hooks під час setup, +встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -| Поле | Обов’язкове | Тип | Що це означає | -| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id провайдера, який показується під час налаштування або онбордингу. | -| `authMethods` | Ні | `string[]` | Id методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env vars, які типові поверхні налаштування/статусу можуть перевіряти до завантаження runtime плагіна. | +Оскільки пошук setup може виконувати код `setup-api`, яким володіє плагін, нормалізовані +значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед +виявлених плагінів. Неоднозначна належність завершується без вибору замість того, щоб +обирати переможця за порядком виявлення. + +### Довідник `setup.providers` + +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Id провайдера, який надається під час setup або онбордингу. Нормалізовані id мають бути глобально унікальними. | +| `authMethods` | Ні | `string[]` | Id методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime плагіна. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------ | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, які показуються під час налаштування та онбордингу. | -| `cliBackends` | Ні | `string[]` | Id backend, доступних під час налаштування без повної активації runtime. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня налаштування цього плагіна. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання runtime плагіна після пошуку дескриптора. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Id backend-ів для часу setup, які використовуються для пошуку setup за принципом descriptor-first. Нормалізовані id мають бути глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього плагіна. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | -## Довідка щодо `uiHints` +## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення. ```json { @@ -310,9 +318,9 @@ OpenClaw читає це до завантаження середовища ви } ``` -Кожна підказка поля може містити: +Кожна підказка для поля може містити: -| Поле | Тип | Що це означає | +| Поле | Тип | Що воно означає | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Мітка поля для користувача. | | `help` | `string` | Короткий допоміжний текст. | @@ -321,10 +329,10 @@ OpenClaw читає це до завантаження середовища ви | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | | `placeholder` | `string` | Текст placeholder для полів форми. | -## Довідка щодо `contracts` +## Довідник `contracts` Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може -читати без імпорту runtime плагіна. +зчитувати без імпорту runtime плагіна. ```json { @@ -344,22 +352,22 @@ OpenClaw читає це до завантаження середовища ви Кожен список є необов’язковим: -| Поле | Тип | Що це означає | -| -------------------------------- | ---------- | -------------------------------------------------------------- | -| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей плагін. | -| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime transcription, якими володіє цей плагін. | -| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime voice, якими володіє цей плагін. | -| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. | -| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. | -| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. | -| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. | -| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей плагін. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для bundled-перевірок контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------- | +| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей плагін. | +| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime-transcription, якими володіє цей плагін. | +| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime-voice, якими володіє цей плагін. | +| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. | +| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. | +| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. | +| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. | +| `webSearchProviders` | `string[]` | Id провайдерів web-search, якими володіє цей плагін. | +| `tools` | `string[]` | Назви agent tool, якими володіє цей плагін, для bundled перевірок контрактів. | -## Довідка щодо `channelConfigs` +## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли плагіну каналу потрібні дешеві метадані конфігурації -до завантаження runtime. +Використовуйте `channelConfigs`, коли плагіну каналу потрібні дешеві метадані конфігурації до +завантаження runtime. ```json { @@ -379,7 +387,7 @@ OpenClaw читає це до завантаження середовища ви } }, "label": "Matrix", - "description": "Підключення до homeserver Matrix", + "description": "Matrix homeserver connection", "preferOver": ["matrix-legacy"] } } @@ -388,18 +396,19 @@ OpenClaw читає це до завантаження середовища ви Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------ | ------------------------ | --------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що зливається в поверхні picker та inspect, коли метадані runtime ще не готові. | -| `description`| `string` | Короткий опис каналу для поверхонь inspect і каталогу. | -| `preferOver` | `string[]` | Id застарілих або нижчопріоритетних плагінів, які цей канал має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується в picker та inspect surfaces, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь inspect і catalog. | +| `preferOver` | `string[]` | Застарілі або нижчопріоритетні id плагінів, які цей канал має випереджати в поверхнях вибору. | -## Довідка щодо `modelSupport` +## Довідник `modelSupport` Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера з -коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime плагіна. +коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime +плагіна. ```json { @@ -410,75 +419,75 @@ OpenClaw читає це до завантаження середовища ви } ``` -OpenClaw застосовує такий пріоритет: +OpenClaw застосовує таку пріоритетність: -- явні посилання `provider/model` використовують метадані маніфесту власника `providers` -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один не-bundled плагін і один bundled-плагін, перемагає не-bundled +- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє плагін +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один небандлований плагін і один bundled plugin, перемагає небандлований плагін -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера +- решта неоднозначностей ігноруються, доки користувач або config не вкаже провайдера Поля: -| Поле | Тип | Що це означає | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` із короткими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються з короткими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ------------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` із короткими id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, які зіставляються з короткими id моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне +`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як належність можливостей. -## Маніфест і package.json +## Маніфест проти package.json -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Для чого його використовувати | +| Файл | Використовуйте його для | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору auth і підказки UI, які мають існувати до запуску коду плагіна | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint-ів, обмежень установлення, setup або метаданих каталогу | Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: -- якщо OpenClaw повинен знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, entry-файлів або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля package.json, які впливають на виявлення Частина метаданих плагіна до runtime навмисно зберігається в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що це означає | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує entrypoint власних плагінів. | -| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. | -| `openclaw.channel` | Легкі метадані каталогу каналів, такі як мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже щось увійшло в систему?» без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled-плагінів і зовнішньо опублікованих плагінів. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із нижньою межею semver, наприклад `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled-плагіна, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє завантажувати поверхні каналу лише для налаштування до повного плагіна каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Оголошує entrypoint-и власних плагінів. | +| `openclaw.setupEntry` | Легковагий entrypoint лише для setup, який використовується під час онбордингу та відкладеного запуску каналу. | +| `openclaw.channel` | Легковагі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легковагі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легковагі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих плагінів. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного плагіна каналу під час запуску. | -`openclaw.install.minHostVersion` перевіряється під час встановлення та +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають плагін на старіших хостах. `openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно -не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення -відновлюватися після певних застарілих збоїв оновлення bundled-плагінів, наприклад відсутнього шляху до bundled-плагіна -або застарілого запису `channels.` для того самого -bundled-плагіна. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів +не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення +відновлюватися після певних застарілих збоїв оновлення bundled plugin, наприклад +відсутнього шляху bundled plugin або застарілого запису `channels.` для того самого +bundled plugin. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакунка для маленького модуля перевірки: ```json { @@ -494,12 +503,11 @@ bundled-плагіна. Непов’язані помилки конфігур } ``` -Використовуйте це, коли потокам налаштування, doctor або configured-state потрібна дешева перевірка автентифікації -так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою -функцією, що лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth +типу так/ні до завантаження повного плагіна каналу. Цільовий export має бути невеликою +функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу. -`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок -налаштованого стану лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок configured-state лише через env: ```json { @@ -515,63 +523,63 @@ bundled-плагіна. Непов’язані помилки конфігур } ``` -Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими -не-runtime входами. Якщо перевірка потребує повного визначення конфігурації або реального -runtime каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`. +Використовуйте це, коли канал може визначити configured-state через env або інші невеликі +входи, не пов’язані з runtime. Якщо перевірка потребує повного розв’язання config або справжнього +runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` плагіна. ## Вимоги до JSON Schema -- **Кожен плагін повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. +- **Кожен плагін має постачатися з JSON Schema**, навіть якщо він не приймає конфігурації. +- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису config, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено - маніфестом плагіна. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошений + у маніфесті плагіна. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **виявлювані** id плагінів. Невідомі id є **помилками**. -- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, + мають посилатися на id плагінів, які **можна виявити**. Невідомі id є **помилками**. +- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна. -- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, і - у Doctor + журналах відображається **попередження**. +- Якщо конфігурація плагіна існує, але сам плагін **вимкнено**, конфігурація зберігається, і + у Doctor + logs відображається **попередження**. -Повну схему `plugins.*` див. у [Довідник конфігурації](/uk/gateway/configuration). +Дивіться [Довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки - Маніфест **обов’язковий для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. -- Runtime і далі завантажує модуль плагіна окремо; маніфест використовується лише для +- Runtime, як і раніше, завантажує модуль плагіна окремо; маніфест призначений лише для виявлення + валідації. - Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та - ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання - тут власних ключів верхнього рівня. -- `providerAuthEnvVars` — це шлях дешевих метаданих для перевірок автентифікації, валідації - env-маркерів та подібних поверхонь автентифікації провайдера, які не повинні запускати runtime плагіна + ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте додавання + власних ключів верхнього рівня сюди. +- `providerAuthEnvVars` — це дешевий шлях метаданих для перевірок auth, валідації + env-marker та подібних поверхонь auth провайдера, які не повинні запускати runtime плагіна лише для перевірки назв env. -- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати vars env автентифікації, - профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу з API key іншого провайдера +- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати auth + env vars, auth profiles, auth на основі config та варіант онбордингу API key іншого провайдера без жорсткого кодування цього зв’язку в core. -- `channelEnvVars` — це шлях дешевих метаданих для fallback через shell-env, підказок налаштування +- `channelEnvVars` — це дешевий шлях метаданих для резервного використання shell-env, підказок setup та подібних поверхонь каналів, які не повинні запускати runtime плагіна лише для перевірки назв env. -- `providerAuthChoices` — це шлях дешевих метаданих для picker варіантів автентифікації, - визначення `--auth-choice`, мапінгу бажаного провайдера та простої реєстрації - прапорців CLI для онбордингу до завантаження runtime провайдера. Для метаданих wizard runtime, - які потребують коду провайдера, див. - [Хуки runtime провайдера](/uk/plugins/architecture#provider-runtime-hooks). -- Виняткові види плагінів вибираються через `plugins.slots.*`. +- `providerAuthChoices` — це дешевий шлях метаданих для picker-ів вибору auth, + розв’язання `--auth-choice`, мапінгу preferred provider і простої реєстрації прапорців CLI + під час онбордингу до завантаження runtime провайдера. Для метаданих wizard runtime, + які потребують коду провайдера, дивіться + [Runtime hooks провайдера](/uk/plugins/architecture#provider-runtime-hooks). +- Виключні типи плагінів вибираються через `plugins.slots.*`. - `kind: "memory"` вибирається через `plugins.slots.memory`. - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` - (типово: вбудований `legacy`). + (типове значення: вбудований `legacy`). - `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагіну вони не потрібні. -- Якщо ваш плагін залежить від native-модулів, задокументуйте кроки збирання та будь-які - вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` +- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та всі + вимоги до allowlist менеджера пакунків (наприклад, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Пов’язане +## Пов’язані матеріали - [Створення плагінів](/uk/plugins/building-plugins) — початок роботи з плагінами - [Архітектура плагінів](/uk/plugins/architecture) — внутрішня архітектура