diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 42dac7512..43b6fcf2e 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,44 +1,44 @@ --- read_when: - Ви створюєте Plugin для OpenClaw - - Потрібно випустити схему конфігурації Plugin або діагностувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin + JSON-схеми (строга валідація конфігурації) + - Потрібно випустити схему конфігурації Plugin або налагодити помилки валідації Plugin +summary: Маніфест Plugin + вимоги до схеми JSON (сувора перевірка конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-30T00:56:13Z" + generated_at: "2026-05-01T21:40:22Z" model: gpt-5.5 provider: openai - source_hash: e71bc192e10504b59dbf587138cfeb3d53ef31e7cbe35d6a8f0672960d318e2d + source_hash: cb611c247a395ad03bef21fe5cf801f66f4529980521996ddda11453b5a0eab2 source_path: plugins/manifest.md workflow: 16 --- Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. -Сумісні макети пакетів див. у [Пакети Plugin](/uk/plugins/bundles). +Про сумісні макети пакетів див. [пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфестів: - Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонентів Claude +- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту - Пакет Cursor: `.cursor-plugin/plugin.json` OpenClaw також автоматично виявляє ці макети пакетів, але вони не перевіряються за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені -корені skill, корені команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude і підтримувані набори hooks, коли макет відповідає +Для сумісних пакетів OpenClaw наразі читає метадані пакета та оголошені +корені Skills, корені команд Claude, стандартні значення `settings.json` пакета Claude, +стандартні значення LSP пакета Claude та підтримувані набори hooks, коли макет відповідає очікуванням runtime OpenClaw. -Кожен нативний Plugin OpenClaw **обов’язково** має постачати файл `openclaw.plugin.json` у +Кожен нативний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для перевірки конфігурації **без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують перевірку конфігурації. Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). -Для нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +Про нативну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл @@ -49,15 +49,15 @@ runtime Plugin. **Використовуйте його для:** -- ідентичності Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації -- метаданих автентифікації, onboarding і налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь control-plane +- ідентичності Plugin, перевірки конфігурації та підказок UI конфігурації +- метаданих автентифікації, onboarding і налаштування (псевдонім, автоматичне ввімкнення, env vars провайдера, варіанти автентифікації) +- підказок активації для поверхонь control plane - скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які може перевіряти спільний host `openclaw qa` -- метаданих конфігурації для конкретних каналів, об’єднаних у каталог і поверхні перевірки +- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти +- метаданих конфігурації для конкретного каналу, об’єднаних у каталог і поверхні перевірки -**Не використовуйте його для:** реєстрації runtime-поведінки, оголошення entrypoints коду +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення точок входу коду або метаданих встановлення npm. Вони належать до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -152,75 +152,74 @@ runtime Plugin. ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що означає | -| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на модель згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та перевірки конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту й використовуються для автоматичного завантаження Plugin перед runtime. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього спискування лише для читання, онбордингу, вибирачів моделей, псевдонімів і придушення без завантаження runtime Plugin. | -| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, що належить провайдеру. Використовуйте її, щоб виключити локальних або самостійно розміщених провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | -| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів ідентифікаторів моделей, що належить провайдеру й має виконуватися до завантаження runtime провайдера. | -| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. | -| `providerRequest` | Ні | `object` | Легкі метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження runtime провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend інференсу CLI, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або CLI backend, для яких синтетичний auth hook, що належить Plugin, має перевірятися під час холодного виявлення моделей до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw досі читає це під час періоду deprecation. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding provider, що спільно використовує API key та auth profiles базового провайдера. | -| `channelEnvVars` | Ні | `Record` | Легкі env-метадані каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації на основі env, які мають бачити загальні helper запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані вибору автентифікації для вибирачів онбордингу, визначення бажаного провайдера та простого підключення CLI flags. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, спричиненого запуском, провайдером, командою, каналом, маршрутом і capability. Лише метадані; фактичною поведінкою досі володіє runtime Plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевірити без завантаження runtime Plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, що використовуються спільним host `openclaw qa` до завантаження runtime Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі стандартні значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються з поверхнями виявлення та перевірки до завантаження runtime. | -| `skills` | Ні | `string[]` | Директорії Skills для завантаження, відносні до кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | UI labels, placeholders і sensitivity hints для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що означає | +| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений за замовчуванням. Опустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб лишити plugin вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей plugin, коли auth, config або посилання на модель згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Id каналів, що належать цьому plugin. Використовується для виявлення та перевірки конфігурації. | +| `providers` | Ні | `string[]` | Id провайдерів, що належать цьому plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легкого модуля виявлення провайдера, відносно кореня plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, які використовуються для автоматичного завантаження plugin перед runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, що належать цьому plugin. Це контракт control-plane для майбутнього read-only спискування, onboarding, вибору моделей, псевдонімів і приглушення без завантаження runtime plugin. | +| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, що належить провайдеру. Використовуйте її, щоб виключити локальних/self-hosted провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з id каталогів OpenRouter/LiteLLM без жорсткого кодування id провайдерів у core. | +| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів id моделей, що належить провайдеру й має виконуватися до завантаження runtime провайдера. | +| `providerEndpoints` | Ні | `object[]` | Метадані endpoint host/baseUrl, що належать маніфесту, для маршрутів провайдерів, які core має класифікувати до завантаження runtime провайдера. | +| `providerRequest` | Ні | `object` | Дешеві метадані сімейства провайдерів і сумісності запитів, які використовуються загальною політикою запитів до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Id backend CLI inference, що належать цьому plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких synthetic auth hook, що належить plugin, має перевірятися під час cold model discovery до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать bundled plugin і представляють несекретний локальний, OAuth або ambient credential стан. | +| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому plugin і мають створювати plugin-aware діагностику конфігурації та CLI до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні env-метадані для пошуку auth/status провайдера. Для нових plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час періоду вилучення. | +| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для auth lookup, наприклад coding provider, що спільно використовує API key базового провайдера й auth profiles. | +| `channelEnvVars` | Ні | `Record` | Дешеві env-метадані каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для env-driven налаштування каналу або auth surfaces, які мають бачити загальні помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані auth-choice для onboarding pickers, preferred-provider resolution і простого wiring прапорів CLI. | +| `activation` | Ні | `object` | Дешеві метадані планувальника активації для startup, provider, command, channel, route і capability-triggered loading. Лише метадані; runtime plugin усе ще відповідає за фактичну поведінку. | +| `setup` | Ні | `object` | Дешеві дескриптори setup/onboarding, які discovery та setup surfaces можуть перевіряти без завантаження runtime plugin. | +| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, які використовуються спільним host `openclaw qa` до завантаження runtime plugin. | +| `contracts` | Ні | `object` | Статичний snapshot bundled capability для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві media-understanding defaults для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються з discovery та validation surfaces до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | +| `name` | Ні | `string` | Зручна для читання назва plugin. | +| `description` | Ні | `string` | Короткий підсумок, що показується на plugin surfaces. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, placeholder-и та підказки чутливості для полів конфігурації. | ## Довідник providerAuthChoices -Кожен запис `providerAuthChoices` описує один вибір онбордингу або автентифікації. +Кожен запис `providerAuthChoices` описує один варіант onboarding або auth. OpenClaw читає це до завантаження runtime провайдера. -Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти -налаштування, отримані з дескрипторів, і метадані install-catalog без завантаження -runtime провайдера. +Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти setup, +отримані з дескрипторів, і метадані install-catalog без завантаження runtime провайдера. -| Поле | Обов’язкове | Тип | Що це означає | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей вибір. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно передати керування. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовують потоки onboarding і CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її не вказано, OpenClaw повертається до `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує вибір із засобів вибору асистента, водночас дозволяючи ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори вибору, які мають перенаправляти користувачів до цього вибору-замінника. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів вибору. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | Поверхні onboarding, на яких має з’являтися цей вибір. Якщо не вказано, типовим значенням є `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | ID постачальника, якому належить цей вибір. | +| `method` | Так | `string` | ID методу автентифікації, до якого потрібно спрямувати. | +| `choiceId` | Так | `string` | Стабільний ID вибору автентифікації, який використовують потоки онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка, видима користувачу. Якщо її пропущено, OpenClaw повертається до `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує вибір із засобів вибору асистента, але все ще дозволяє ручний вибір у CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ID вибору, які мають переспрямовувати користувачів до цього вибору-заміни. | +| `groupId` | Ні | `string` | Необов’язковий ID групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка для цієї групи, видима користувачу. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей вибір. Якщо пропущено, типовим значенням є `["text-inference"]`. | -## довідка commandAliases +## Довідник commandAliases -Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть +Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. +використовує ці метадані для діагностики без імпорту runtime-коду Plugin. ```json { @@ -234,52 +233,52 @@ runtime провайдера. } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо така існує. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------- | ----------- | ----------------- | -------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку варто запропонувати для операцій CLI, якщо така існує. | -## довідка activation +## Довідник activation -Використовуйте `activation`, коли plugin може дешево оголосити, які події площини керування +Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку середовища виконання, не замінює `register(...)` і не гарантує, що -код plugin уже виконано. Планувальник активації використовує ці поля, щоб -звузити список кандидатів plugin перед поверненням до наявних метаданих володіння маніфесту, -таких як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. +Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє +runtime-поведінку, не замінює `register(...)` і не гарантує, що +код Plugin уже виконано. Планувальник активації використовує ці поля, щоб +звузити список кандидатів Plugin перед fallback до наявних метаданих володіння +маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і hooks. -Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори налаштування або `contracts`, +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок -планувальнику, які неможливо представити цими полями володіння. -Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, +планувальнику, які не можна представити цими полями володіння. +Використовуйте top-level `cliBackends` для runtime-alias CLI, як-от `claude-cli`, `codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для -вбудованих ідентифікаторів агентних harness, які ще не мають поля володіння. +вбудованих ID agent harness, які ще не мають поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання й не -замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому -відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не повинна -змінювати коректність, доки ще існують застарілі резервні механізми володіння маніфесту. +Цей блок є лише метаданими. Він не реєструє runtime-поведінку і не +замінює `register(...)`, `setupEntry` чи інші runtime/plugin entrypoints. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому +відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не має +змінювати коректність, доки ще існують legacy fallback володіння маніфесту. -Кожен plugin має свідомо встановлювати `activation.onStartup`, оскільки OpenClaw відходить -від неявних імпортів під час запуску. Встановлюйте його в `true` лише тоді, коли plugin повинен -виконуватися під час запуску Gateway. Встановлюйте його в `false`, коли plugin інертний під час -запуску й має завантажуватися лише через вужчі тригери. Пропуск `onStartup` зберігає -застарілий резервний механізм неявного sidecar під час запуску для plugin без -статичних метаданих можливостей; майбутні версії можуть припинити завантажувати такі -plugin під час запуску, якщо вони не оголосять `activation.onStartup: true`. Звіти про стан і -сумісність plugin попереджають `legacy-implicit-startup-sidecar`, коли plugin -досі покладається на цей резервний механізм. +Кожен Plugin має свідомо встановлювати `activation.onStartup`, оскільки OpenClaw переходить +від неявних startup-імпортів. Установіть його в `true` лише тоді, коли Plugin повинен +виконуватися під час запуску Gateway. Установіть його в `false`, коли Plugin інертний під час +startup і має завантажуватися лише через вужчі тригери. Пропуск `onStartup` зберігає +застарілий legacy implicit startup sidecar fallback для Plugin без +статичних метаданих можливостей; майбутні версії можуть припинити startup-завантаження цих +Plugin, якщо вони не оголосять `activation.onStartup: true`. Звіти про статус і сумісність +Plugin попереджають із `legacy-implicit-startup-sidecar`, коли Plugin +досі покладається на цей fallback. Для тестування міграції встановіть `OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1`, щоб вимкнути лише цей -застарілий резервний механізм. Цей режим із явним увімкненням не блокує plugin з явним -`activation.onStartup: true` або plugin, завантажені каналом, конфігурацією, +застарілий fallback. Цей opt-in режим не блокує явні +Plugin з `activation.onStartup: true` або Plugin, завантажені каналом, конфігурацією, agent-harness, пам’яттю чи іншими вужчими тригерами активації. ```json @@ -296,45 +295,45 @@ agent-harness, пам’яттю чи іншими вужчими тригера } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------------ | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен plugin має встановлювати це поле. `true` імпортує plugin під час запуску; `false` відмовляється від застарілого неявного резервного запуску sidecar, якщо інший відповідний тригер не потребує завантаження. | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Використовуйте верхньорівневий `cliBackends` для псевдонімів backend CLI. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей plugin до планів запуску/завантаження, коли шлях наявний і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовуються плануванням активації площини керування. Коли можливо, віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час запуску; `false` відмовляється від застарілого implicit sidecar startup fallback, якщо інший відповідний тригер не вимагає завантаження. | +| `onProviders` | Ні | `string[]` | ID постачальників, які мають включати цей Plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Runtime ID вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте top-level `cliBackends` для alias backend CLI. | +| `onCommands` | Ні | `string[]` | ID команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | ID каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів startup/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовує планування активації control plane. Надавайте перевагу вужчим полям, коли це можливо. | Поточні live-споживачі: -- планування запуску Gateway використовує `activation.onStartup` для явного імпорту - під час запуску та відмови від застарілого неявного резервного запуску sidecar -- планування CLI, викликане командою, повертається до застарілих +- Планування запуску Gateway використовує `activation.onStartup` для явного startup + імпорту та відмови від застарілого implicit sidecar startup fallback +- планування CLI, запущене командою, fallback до legacy `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску середовища виконання агента використовує `activation.onAgentHarnesses` для - вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI -- планування налаштування/каналу, викликане каналом, повертається до застарілого володіння `channels[]`, - коли відсутні явні метадані активації каналу -- планування plugin під час запуску використовує `activation.onConfigPaths` для неканальних кореневих - поверхонь конфігурації, таких як блок `browser` вбудованого browser plugin -- планування налаштування/середовища виконання, викликане провайдером, повертається до застарілого володіння - `providers[]` і верхньорівневого `cliBackends[]`, коли відсутні явні метадані - активації провайдера +- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для + вбудованих harness і top-level `cliBackends[]` для runtime-alias CLI +- планування setup/каналу, запущене каналом, fallback до legacy `channels[]` + володіння, коли явні метадані активації каналу відсутні +- планування Plugin під час startup використовує `activation.onConfigPaths` для неканальних root + поверхонь конфігурації, як-от блок `browser` вбудованого browser Plugin +- планування setup/runtime, запущене постачальником, fallback до legacy + `providers[]` і top-level `cliBackends[]` володіння, коли явні метадані активації постачальника + відсутні -Діагностика планувальника може відрізняти явні підказки активації від резервного +Діагностика планувальника може відрізняти явні підказки активації від fallback володіння маніфесту. Наприклад, `activation-command-hint` означає, що -`activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста й тестів; автори plugin мають і далі оголошувати метадані, +`activation.onCommands` збігся, а `manifest-command-alias` означає, що +планувальник натомість використав володіння `commandAliases`. Ці reason labels призначені для +діагностики хоста й тестів; автори Plugin мають і надалі оголошувати метадані, які найкраще описують володіння. -## довідка qaRunners +## Довідник qaRunners -Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner під -спільним коренем `openclaw qa`. Тримайте ці метадані дешевими та статичними; середовище -виконання plugin усе одно володіє фактичною реєстрацією CLI через легку +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під +спільним коренем `openclaw qa`. Тримайте ці метадані дешевими й статичними; runtime +Plugin усе ще володіє фактичною реєстрацією CLI через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json @@ -348,15 +347,15 @@ agent-harness, пам’яттю чи іншими вужчими тригера } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------- | ----------- | -------- | -------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна заглушкова команда. | +| Поле | Обов’язкове | Тип | Що означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний довідковий текст, що використовується, коли спільному хосту потрібна команда-заглушка. | -## довідка setup +## довідник setup -Використовуйте `setup`, коли поверхням налаштування й onboarding потрібні дешеві метадані, належні Plugin, -до завантаження runtime. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, що належать plugin, +перш ніж завантажиться runtime. ```json { @@ -384,83 +383,83 @@ agent-harness, пам’яттю чи іншими вужчими тригера } ``` -Верхньорівневий `cliBackends` залишається чинним і продовжує описувати backend-и виведення CLI. +Верхньорівневий `cliBackends` залишається чинним і далі описує бекенди CLI-виведення. `setup.cliBackends` — це специфічна для setup поверхня дескрипторів для потоків control-plane/setup, які мають залишатися лише метаданими. -Коли вони наявні, `setup.providers` і `setup.cliBackends` є бажаною -поверхнею пошуку за принципом descriptor-first для виявлення setup. Якщо дескриптор лише -звужує кандидата Plugin, а setup все ще потребує багатших runtime-хуків часу setup, -задайте `requiresRuntime: true` і залиште `setup-api` як +Коли `setup.providers` і `setup.cliBackends` наявні, вони є пріоритетною +поверхнею пошуку за дескрипторами для виявлення setup. Якщо дескриптор лише +звужує кандидатний plugin, а setup все ще потребує багатших runtime-хуків під час налаштування, +установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки auth провайдера та -env-var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності -протягом вікна застарівання, але небандловані plugins, які все ще його використовують, -отримують діагностику маніфесту. Нові plugins мають розміщувати метадані env для setup/status +OpenClaw також включає `setup.providers[].envVars` у загальну автентифікацію provider і +пошуки env-var. `providerAuthEnvVars` лишається підтримуваним через адаптер сумісності +під час вікна застарівання, але небандловані plugins, які досі його використовують, +отримують діагностику manifest. Нові plugins мають розміщувати метадані env для setup/status у `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, +OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` -оголошує runtime setup непотрібним. Явні записи `providerAuthChoices` залишаються -бажаними для кастомних міток, прапорців CLI, області onboarding і метаданих асистента. +оголошує, що runtime для setup не потрібен. Явні записи `providerAuthChoices` лишаються +пріоритетними для кастомних міток, CLI-прапорців, області онбордингу та метаданих assistant. -Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескрипторах і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin лише з дескрипторами все ще постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущений +plugin лише з дескрипторами все одно постачає один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику й продовжує її ігнорувати. Пропущений `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали -дескриптори без прапорця, не зламалися. +дескриптори без цього прапорця, не зламалися. -Оскільки пошук setup може виконувати код `setup-api`, належний Plugin, нормалізовані +Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -виявлених plugins. Неоднозначне володіння завершується закрито, замість вибору -переможця з порядку виявлення. +виявлених plugins. Неоднозначне володіння завершується відмовою замість вибору +переможця за порядком виявлення. -Коли runtime setup виконується, діагностика реєстру setup повідомляє про розбіжність дескрипторів, -якщо `setup-api` реєструє провайдера або backend CLI, які дескриптори маніфесту -не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. -Ці діагностики є додатковими й не відхиляють застарілі plugins. +Коли runtime setup таки виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, +якщо `setup-api` реєструє provider або CLI-бекенд, які не оголошені дескрипторами +manifest, або якщо дескриптор не має відповідної runtime-реєстрації. +Ця діагностика є додатковою й не відхиляє застарілі plugins. -### довідка setup.providers +### довідник setup.providers -| Поле | Обов’язкове | Тип | Що це означає | -| -------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | ID провайдера, доступний під час setup або onboarding. Тримайте нормалізовані ID глобально унікальними. | -| `authMethods` | Ні | `string[]` | ID методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | -| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів auth для провайдерів, які можуть автентифікуватися через несекретні маркери. | +| Поле | Обов’язкове | Тип | Що означає | +| -------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Id provider, відкритий під час setup або онбордингу. Тримайте нормалізовані id глобально унікальними. | +| `authMethods` | Ні | `string[]` | Id методів setup/auth, які цей provider підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. | +| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів auth для providers, що можуть автентифікуватися через несекретні маркери. | -`authEvidence` призначено для локальних маркерів облікових даних, належних провайдеру, які можна -перевірити без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: +`authEvidence` призначено для локальних маркерів облікових даних, що належать provider і можуть бути +перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або secret-manager, без shell-команд і без -проб API провайдера. +проб provider API. Підтримувані записи доказів: -| Поле | Обов’язкове | Тип | Що це означає | -| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------- | -| `type` | Так | `string` | Наразі `local-file-with-env`. | -| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файлу облікових даних. | -| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | -| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна з перелічених env vars має бути непорожньою, перш ніж доказ стане чинним. | -| `requiresAllEnv` | Ні | `string[]` | Кожна перелічена env var має бути непорожньою, перш ніж доказ стане чинним. | -| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | -| `source` | Ні | `string` | Користувацька мітка джерела для виводу auth/status. | +| Поле | Обов’язкове | Тип | Що означає | +| ----------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------- | +| `type` | Так | `string` | Наразі `local-file-with-env`. | +| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файла облікових даних. | +| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, що перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | +| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна з перелічених env var має бути непорожньою, перш ніж доказ стане чинним. | +| `requiresAllEnv` | Ні | `string[]` | Кожна перелічена env var має бути непорожньою, перш ніж доказ стане чинним. | +| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | +| `source` | Ні | `string` | Користувацька мітка джерела для виводу auth/status. | ### поля setup -| Поле | Обов’язкове | Тип | Що це означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup і onboarding. | -| `cliBackends` | Ні | `string[]` | ID backend-ів часу setup, що використовуються для пошуку setup за принципом descriptor-first. Тримайте нормалізовані ID глобально унікальними. | -| `configMigrations` | Ні | `string[]` | ID міграцій конфігурації, належні поверхні setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку дескрипторів. | +| Поле | Обов’язкове | Тип | Що означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------ | +| `providers` | Ні | `object[]` | Дескриптори setup provider, відкриті під час setup і онбордингу. | +| `cliBackends` | Ні | `string[]` | Id бекендів часу setup, що використовуються для пошуку setup спершу за дескрипторами. Тримайте нормалізовані id глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, що належать поверхні setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку за дескрипторами. | -## довідка uiHints +## довідник uiHints -`uiHints` — це мапа від назв полів конфігурації до малих підказок рендерингу. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. ```json { @@ -477,19 +476,19 @@ OpenClaw повідомляє додаткову діагностику й пр Кожна підказка поля може містити: -| Поле | Тип | Що це означає | -| ------------- | ---------- | ------------------------------------- | -| `label` | `string` | Користувацька мітка поля. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теги. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст заповнювача для полів форми. | +| Поле | Тип | Що означає | +| ------------- | ---------- | ------------------------------------------- | +| `label` | `string` | Користувацька мітка поля. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові UI-теги. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст заповнювача для полів форми. | -## довідка contracts +## довідник contracts Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може -читати без імпорту runtime Plugin. +читати без імпорту runtime plugin. ```json { @@ -511,48 +510,48 @@ OpenClaw повідомляє додаткову діагностику й пр } ``` -Кожен список є необов’язковим: +Кожен список необов’язковий: -| Поле | Тип | Що це означає | -| -------------------------------- | ---------- | ---------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | ID фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Runtime ID, для яких бандлований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | ID провайдерів, чиїм хуком зовнішнього auth-профілю володіє цей Plugin. | -| `speechProviders` | `string[]` | ID провайдерів мовлення, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | ID провайдерів realtime-транскрипції, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | ID провайдерів realtime-голосу, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | ID провайдерів memory embedding, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | ID провайдерів media-understanding, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | ID провайдерів image-generation, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | ID провайдерів video-generation, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | ID провайдерів Web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | ID провайдерів Web-search, якими володіє цей Plugin. | -| `migrationProviders` | `string[]` | ID провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для бандлованих перевірок контрактів. | +| Поле | Тип | Що означає | +| -------------------------------- | ---------- | -------------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Id фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Runtime id, для яких бандлований plugin може зареєструвати middleware результатів tool. | +| `externalAuthProviders` | `string[]` | Id provider, чий хук зовнішнього профілю auth належить цьому plugin. | +| `speechProviders` | `string[]` | Id speech provider, що належать цьому plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Id realtime-transcription provider, що належать цьому plugin. | +| `realtimeVoiceProviders` | `string[]` | Id realtime-voice provider, що належать цьому plugin. | +| `memoryEmbeddingProviders` | `string[]` | Id memory embedding provider, що належать цьому plugin. | +| `mediaUnderstandingProviders` | `string[]` | Id media-understanding provider, що належать цьому plugin. | +| `imageGenerationProviders` | `string[]` | Id image-generation provider, що належать цьому plugin. | +| `videoGenerationProviders` | `string[]` | Id video-generation provider, що належать цьому plugin. | +| `webFetchProviders` | `string[]` | Id web-fetch provider, що належать цьому plugin. | +| `webSearchProviders` | `string[]` | Id web-search provider, що належать цьому plugin. | +| `migrationProviders` | `string[]` | Id import provider, що належать цьому plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви agent tools, що належать цьому plugin для бандлованих перевірок контрактів. | `contracts.embeddedExtensionFactories` збережено для бандлованих фабрик розширень Codex, -призначених лише для app-server. Бандловані перетворення результатів інструментів мають +призначених лише для app-server. Бандловані перетворення результатів tool мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)` натомість. Зовнішні plugins не можуть -реєструвати middleware результатів інструментів, бо seam може переписувати високодовірений вивід інструментів -до того, як модель його побачить. +`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть +реєструвати middleware результатів tool, оскільки цей seam може переписувати вивід tool +із високим рівнем довіри до того, як його побачить модель. -Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugins без такого оголошення все ще запускаються -через застарілий резервний шлях сумісності, але цей резервний шлях повільніший і +Provider plugins, що реалізують `resolveExternalAuthProfiles`, мають оголошувати +`contracts.externalAuthProviders`. Plugins без цього оголошення все одно проходять +через застарілий резервний шлях сумісності, але він повільніший і буде вилучений після вікна міграції. -Бандловані провайдери memory embedding мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного ID адаптера, який вони надають, включно з -вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт -маніфесту, щоб завантажити лише Plugin-власник до того, як повний runtime Gateway -зареєструє провайдерів. +Бандловані providers memory embedding мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони відкривають, зокрема +вбудованих адаптерів на кшталт `local`. Самостійні CLI-шляхи використовують цей manifest +contract, щоб завантажити лише власний plugin до того, як повний runtime Gateway +зареєструє providers. -## довідка mediaUnderstandingProviderMetadata +## довідник mediaUnderstandingProviderMetadata -Використовуйте `mediaUnderstandingProviderMetadata`, коли постачальник розуміння медіа має -моделі за замовчуванням, пріоритет резервного автоматичного автентифікування або нативну підтримку документів, які -потрібні загальним основним помічникам до завантаження середовища виконання. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет резервної автоавтентифікації або вбудовану підтримку документів, +які потрібні загальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -576,26 +575,26 @@ Plugins провайдерів, які реалізують `resolveExternalAuth } ``` -Кожен запис постачальника може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що це означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей постачальник. | -| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору постачальника на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує постачальник. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові зіставлення можливостей із моделями, що використовуються, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані вхідні документи, які підтримує провайдер. | -## Довідник channelConfigs +## Довідник `channelConfigs` Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження середовища виконання. Виявлення налаштування/стану каналу лише для читання може використовувати ці метадані +завантаження середовища виконання. Виявлення налаштування/стану каналу в режимі лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний, або -коли `setup.requiresRuntime: false` оголошує, що середовище виконання для налаштування не потрібне. +коли `setup.requiresRuntime: false` оголошує, що середовище виконання для налаштування непотрібне. -`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ конфігурації користувача +`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ користувацької конфігурації верхнього рівня. Користувачі й надалі налаштовують екземпляри каналів у `channels.`. OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим -каналом до виконання коду середовища виконання Plugin. +каналом, до виконання коду середовища виконання Plugin. Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: @@ -603,15 +602,15 @@ OpenClaw читає метадані маніфесту, щоб визначит - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` -Невбудовані Plugins, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але -схема конфігурації холодного шляху, налаштування та поверхні Control UI не зможуть знати +Невбудовані plugins, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але +схема конфігурації, налаштування й поверхні інтерфейсу керування на холодному шляху не зможуть знати форму параметрів, що належать каналу, доки не виконається середовище виконання Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні значення `auto` за замовчуванням для перевірок конфігурації команд, +`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати -такі самі значення за замовчуванням через `package.json#openclaw.channel.commands` разом +такі самі типові значення через `package.json#openclaw.channel.commands` разом з іншими метаданими каталогу каналів, що належать пакету. ```json @@ -645,19 +644,19 @@ OpenClaw читає метадані маніфесту, щоб визначит Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові підписи UI, заповнювачі та підказки щодо чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Підпис каналу, що об’єднується з поверхнями вибору та інспектування, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | -| `commands` | `object` | Статичні значення автоматичного ввімкнення нативних команд і нативних Skills для перевірок конфігурації до середовища виконання. | -| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори Plugin, які цей канал має випереджати на поверхнях вибору. | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | ------------------------------------------------------------------------------ | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові підказки для міток/заповнювачів/чутливих даних інтерфейсу для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору й інспектування, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспектування й каталогу. | +| `commands` | `object` | Статичні автоматичні типові значення вбудованих команд і вбудованих Skills для перевірок конфігурації до середовища виконання. | +| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори plugins, які цей канал має випереджати на поверхнях вибору. | ### Заміна іншого Plugin каналу Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Типові випадки — перейменований ідентифікатор Plugin, +може також надавати інший Plugin. Типові випадки — перейменований ідентифікатор Plugin, окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який зберігає той самий ідентифікатор каналу для сумісності конфігурації. @@ -680,21 +679,21 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Коли `channels.chat` налаштовано, OpenClaw враховує і ідентифікатор каналу, і -ідентифікатор бажаного Plugin. Якщо Plugin нижчого пріоритету було вибрано лише тому, що +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та +ідентифікатор бажаного Plugin. Якщо нижчопріоритетний Plugin було вибрано лише тому, що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній -конфігурації середовища виконання, щоб каналом і його інструментами володів один Plugin. Явний -вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugins, OpenClaw +конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача +все одно має перевагу: якщо користувач явно вмикає обидва plugins, OpenClaw зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість -мовчазної зміни запитаного набору Plugins. +тихої зміни запитаного набору plugins. -Обмежуйте `preferOver` ідентифікаторами Plugins, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету, і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` лише ідентифікаторами plugins, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. -## Довідник modelSupport +## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin постачальника з -коротких ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +скорочених ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin. ```json @@ -706,28 +705,27 @@ Plugin. } ``` -OpenClaw застосовує такий порядок пріоритету: +OpenClaw застосовує такий порядок пріоритетів: - явні посилання `provider/model` використовують метадані маніфесту `providers` власника - `modelPatterns` мають перевагу над `modelPrefixes` - якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть постачальника +- решта неоднозначностей ігнорується, доки користувач або конфігурація не задасть провайдера Поля: -| Поле | Тип | Що це означає | -| --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` із короткими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела регулярних виразів, які зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела регулярних виразів, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -## Довідник modelCatalog +## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей постачальника до +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до завантаження середовища виконання Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, -псевдонімів постачальників, правил пригнічення та режиму виявлення. Оновлення середовища виконання -й надалі належить коду середовища виконання постачальника, але маніфест повідомляє core, коли середовище виконання -потрібне. +псевдонімів провайдерів, правил пригнічення та режиму виявлення. Оновлення середовища виконання +й надалі належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли потрібне середовище виконання. ```json { @@ -778,71 +776,71 @@ OpenClaw застосовує такий порядок пріоритету: Поля верхнього рівня: -| Поле | Тип | Що це означає | -| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів постачальників, що належать цьому Plugin. Ключі також мають бути присутні в `providers` верхнього рівня. | -| `aliases` | `Record` | Псевдоніми постачальників, які мають розв’язуватися у власного постачальника для планування каталогу або пригнічення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin пригнічує з причини, специфічної для постачальника. | -| `discovery` | `Record` | Чи можна читати каталог постачальника з метаданих маніфесту, оновлювати його в кеш або чи він потребує середовища виконання. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, що належать цьому Plugin. Ключі також мають з’являтися в `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися до власного провайдера для планування каталогу або пригнічення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin пригнічує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати його в кеш або чи потрібне середовище виконання. | -`aliases` бере участь у пошуку власника постачальника для планування каталогу моделей. -Цілі псевдонімів мають бути постачальниками верхнього рівня, що належать тому самому Plugin. Коли -список, відфільтрований за постачальником, використовує псевдонім, OpenClaw може прочитати маніфест власника та -застосувати перевизначення API/базової URL-адреси псевдоніма без завантаження середовища виконання постачальника. +`aliases` бере участь у пошуку власника провайдера для планування каталогу моделей. +Цілі псевдонімів мають бути провайдерами верхнього рівня, що належать тому самому Plugin. Коли +список, відфільтрований за провайдером, використовує псевдонім, OpenClaw може читати маніфест власника та +застосовувати перевизначення API/базової URL-адреси псевдоніма без завантаження середовища виконання провайдера. Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки -канонічного постачальника-власника. +канонічного провайдера-власника. -`suppressions` замінює старий хук середовища виконання постачальника `suppressBuiltInModel`. -Записи пригнічення враховуються лише тоді, коли постачальник належить Plugin або -оголошений як ключ `modelCatalog.aliases`, що вказує на власного постачальника. Хуки пригнічення +`suppressions` замінює старий хук середовища виконання провайдера `suppressBuiltInModel`. +Записи пригнічення враховуються лише тоді, коли провайдер належить Plugin або +оголошений як ключ `modelCatalog.aliases`, що вказує на власного провайдера. Хуки пригнічення середовища виконання більше не викликаються під час розв’язання моделей. -Поля постачальника: +Поля провайдера: -| Поле | Тип | Що це означає | -| --------- | ------------------------ | ----------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язкова базова URL-адреса за замовчуванням для моделей у цьому каталозі постачальника. | -| `api` | `ModelApi` | Необов’язковий адаптер API за замовчуванням для моделей у цьому каталозі постачальника. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу постачальника. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що це означає | +| --------- | ------------------------ | -------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язкова типова базова URL-адреса для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | +| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що це означає | -| --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов'язкова відображувана назва. | -| `api` | `ModelApi` | Необов'язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов'язкове перевизначення базової URL-адреси для окремої моделі. | -| `headers` | `Record` | Необов'язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Власне контекстне вікно провайдера. | -| `contextTokens` | `number` | Необов'язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов'язкова ціна в USD за мільйон токенів, включно з необов'язковим `tieredPricing`. | -| `compat` | `object` | Необов'язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Стан у списку. Приховуйте лише тоді, коли рядок взагалі не має з'являтися. | -| `statusReason` | `string` | Необов'язкова причина, показана зі станом, відмінним від доступного. | -| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору й фільтри. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі, без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення базової URL-адреси для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку міркування. | +| `contextWindow` | `number` | Нативне контекстне вікно провайдера. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, коли воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язкове `tieredPricing`. | +| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок узагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від доступного. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору та фільтри. | -Поля пригнічення: +Поля приховування: -| Поле | Тип | Що це означає | -| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно пригнітити. Має належати цьому плагіну або бути оголошеним як власний псевдонім. | -| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно пригнітити. | -| `reason` | `string` | Необов'язкове повідомлення, показане, коли пригнічений рядок запитують напряму. | -| `when.baseUrlHosts` | `string[]` | Необов'язковий список ефективних хостів базової URL-адреси провайдера, потрібних перед застосуванням пригнічення. | -| `when.providerConfigApiIn` | `string[]` | Необов'язковий список точних значень `api` з конфігурації провайдера, потрібних перед застосуванням пригнічення. | +| Поле | Тип | Що це означає | +| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно приховати. Має належати цьому plugin або бути оголошеним як належний псевдонім. | +| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно приховати. | +| `reason` | `string` | Необов’язкове повідомлення, що показується, коли прихований рядок запитують напряму. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базових URL провайдера, потрібних перед застосуванням приховування. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` з конфігурації провайдера, потрібних перед застосуванням приховування. | -Не розміщуйте дані лише часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку, відфільтрованого за провайдером, і засоби вибору могли пропустити виявлення через registry/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення/кеш може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб знати список. +Не розміщуйте дані лише часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку з фільтрацією за провайдером і засоби вибору могли пропустити виявлення через реєстр або runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення чи кеш можуть додати більше рядків пізніше; рядки `refreshable` самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб знати список. -## Довідка `modelIdNormalization` +## Довідка modelIdNormalization -Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, яким володіє провайдер, що має відбутися до завантаження runtime провайдера. Це тримає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті власного плагіна, а не в таблицях вибору моделей ядра. +Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, що належить провайдеру й має відбутися до завантаження runtime провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті власного plugin, а не в основних таблицях вибору моделей. ```json { @@ -864,31 +862,31 @@ OpenClaw застосовує такий порядок пріоритету: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- | +| Поле | Тип | Що це означає | +| ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------- | | `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | -| `stripPrefixes` | `string[]` | Префікси, які потрібно вилучити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса для bare-id після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | +| `stripPrefixes` | `string[]` | Префікси, які потрібно видалити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | +| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксації bare-id після пошуку псевдоніма, ключовані за `modelPrefix` і `prefix`. | -## Довідка `providerEndpoints` +## Довідка providerEndpoints -Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Ядро все ще володіє значенням кожного `endpointClass`; маніфести плагінів володіють метаданими хоста та базової URL-адреси. +Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Core і далі володіє значенням кожного `endpointClass`; маніфести plugin володіють метаданими хоста й базової URL-адреси. Поля endpoint: -| Поле | Тип | Що це означає | -| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | Відомий клас endpoint ядра, як-от `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом endpoint. | -| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом endpoint. Починайте з `.` для зіставлення лише суфікса домену. | -| `baseUrls` | `string[]` | Точні нормалізовані базові URL-адреси HTTP(S), які зіставляються з класом endpoint. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | +| Поле | Тип | Що це означає | +| ----------------------------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | Відомий core-клас endpoint, як-от `openrouter`, `moonshot-native` або `google-vertex`. | +| `hosts` | `string[]` | Точні імена хостів, що відповідають класу endpoint. | +| `hostSuffixes` | `string[]` | Суфікси хостів, що відповідають класу endpoint. Додавайте префікс `.` для зіставлення лише суфікса домену. | +| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, що відповідають класу endpoint. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | -## Довідка `providerRequest` +## Довідка providerRequest -Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Тримайте специфічне для поведінки переписування payload у runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів. +Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Тримайте переписування payload, специфічне для поведінки, у runtime-хуках провайдера або спільних допоміжних функціях сімейства провайдерів. ```json { @@ -908,15 +906,15 @@ OpenClaw застосовує такий порядок пріоритету: Поля провайдера: -| Поле | Тип | Що це означає | -| --------------------- | ------------ | ------------------------------------------------------------------------------------- | -| `family` | `string` | Мітка сімейства провайдера, яку використовують загальні рішення сумісності запитів і діагностика. | -| `compatibilityFamily` | `"moonshot"` | Необов'язковий кошик сумісності сімейства провайдерів для спільних допоміжних засобів запитів. | -| `openAICompletions` | `object` | Прапорці OpenAI-сумісних completion-запитів, наразі `supportsStreamingUsage`. | +| Поле | Тип | Що це означає | +| --------------------- | ------------ | ---------------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства провайдерів, яку використовують загальні рішення щодо сумісності запитів і діагностика. | +| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства провайдерів для спільних допоміжних функцій запитів. | +| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | -## Довідка `modelPricing` +## Довідка modelPricing -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш цін Gateway читає ці метадані без імпорту коду runtime провайдера. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш ціноутворення Gateway читає ці метадані без імпорту коду runtime провайдера. ```json { @@ -939,133 +937,133 @@ OpenClaw застосовує такий порядок пріоритету: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| Поле | Тип | Що це означає | +| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------ | +| `external` | `boolean` | Установіть `false` для локальних або self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Відображення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Відображення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що це означає | -| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| Поле | Тип | Що це означає | +| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------ | | `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядайте ідентифікатори моделей зі скісною рискою як вкладені посилання provider/model; корисно для проксі-провайдерів, як-от OpenRouter. | +| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей із скісною рискою як вкладені посилання provider/model, корисно для проксі-провайдерів, таких як OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw - це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї плагіни ще можуть бути не встановлені. Він не є частиною маніфесту плагіна. Маніфести плагінів залишаються авторитетним джерелом установлених плагінів. Індекс провайдерів - це внутрішній fallback-контракт, який майбутні поверхні installable-provider і pre-install засобу вибору моделей використовуватимуть, коли плагін провайдера не встановлено. +Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом щодо встановлених plugin. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні installable-provider і засобів вибору моделей до встановлення використовуватимуть, коли plugin провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. `modelCatalog` маніфесту встановленого плагіна. +2. `modelCatalog` маніфесту встановленого plugin. 3. Кеш каталогу моделей після явного оновлення. 4. Preview-рядки Індексу провайдерів OpenClaw. -Індекс провайдерів не має містити секрети, увімкнений стан, runtime hooks або -актуальні дані моделей, специфічні для облікового запису. Його каталоги попереднього перегляду використовують ту саму форму рядка провайдера -`modelCatalog`, що й маніфести plugin, але мають залишатися обмеженими -стабільними відображуваними метаданими, якщо поля runtime-адаптера, як-от `api`, -`baseUrl`, ціни або прапорці сумісності, навмисно не підтримуються узгодженими з -маніфестом установленого plugin. Провайдери з актуальним виявленням `/models` мають -записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати -звичайний listing чи onboarding викликати API провайдера. +Індекс провайдерів не повинен містити секрети, увімкнений стан, runtime-хуки або +живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести плагінів, але мають залишатися обмеженими +стабільними метаданими відображення, якщо поля runtime-адаптера, як-от `api`, +`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з +маніфестом установленого плагіна. Провайдери з live-виявленням `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, +щоб звичайний список або onboarding викликав API провайдера. Записи Індексу провайдерів також можуть містити метадані installable-plugin для провайдерів, -чий plugin було винесено з core або який інакше ще не встановлено. Ці -метадані віддзеркалюють шаблон каталогу каналів: назви package, npm install spec, -очікувана integrity та дешеві мітки вибору auth достатні, щоб показати -варіант installable setup. Після встановлення plugin його маніфест має пріоритет, а +чий плагін було винесено з core або інакше ще не встановлено. Ці +метадані віддзеркалюють патерн каталогу каналів: назви пакета, npm install spec, +очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати +інсталюваний варіант налаштування. Після встановлення плагіна його маніфест має пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі capability keys верхнього рівня вважаються застарілими. Використовуйте `openclaw doctor --fix`, щоб +Застарілі capability-ключі верхнього рівня deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне -завантаження маніфесту більше не розглядає ці поля верхнього рівня як ownership +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне +завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння capability. -## Маніфест проти package.json +## Manifest проти package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, перевірка config, метадані вибору auth і підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | метадані npm, встановлення dependency та блок `openclaw`, що використовується для entrypoints, install gating, setup або метаданих catalog | +| `openclaw.plugin.json` | Виявлення, валідація config, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду плагіна | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint-ів, install gating, setup або метаданих каталогу | -Якщо ви не впевнені, де має бути певний фрагмент метаданих, скористайтеся цим правилом: +Якщо ви не впевнені, де має бути певна частина метаданих, скористайтеся цим правилом: -- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується packaging, entry files або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, entry-файлів або поведінки npm install, помістіть це в `package.json` -### Поля package.json, що впливають на виявлення +### Поля package.json, які впливають на виявлення -Деякі pre-runtime метадані plugin навмисно зберігаються в `package.json` у блоці -`openclaw`, а не в `openclaw.plugin.json`. +Деякі pre-runtime метадані плагіна навмисно живуть у `package.json` під +блоком `openclaw` замість `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує native entrypoints plugin. Має залишатися всередині директорії package plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoints для встановлених packages. Має залишатися всередині директорії package plugin. | -| `openclaw.setupEntry` | Легковагий setup-only entrypoint, що використовується під час onboarding, відкладеного запуску каналів і read-only status каналу/виявлення SecretRef. Має залишатися всередині директорії package plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript setup entrypoint для встановлених packages. Має залишатися всередині директорії package plugin. | -| `openclaw.channel` | Дешеві метадані catalog каналу, як-от мітки, шляхи docs, aliases і текст вибору. | -| `openclaw.channel.commands` | Статичні метадані native command і native skill auto-default, що використовуються config, audit і поверхнями списку команд до завантаження runtime каналу. | -| `openclaw.channel.configuredState` | Легковагі метадані configured-state checker, які можуть відповісти "чи вже існує env-only setup?" без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Легковагі метадані persisted-auth checker, які можуть відповісти "чи вже хтось увійшов?" без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки install/update для bundled і зовнішньо опублікованих plugins. | -| `openclaw.install.defaultChoice` | Бажаний шлях install, коли доступно кілька install sources. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія host OpenClaw, із semver floor на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок npm dist integrity, як-от `sha512-...`; потоки install і update перевіряють отриманий artifact за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення reinstall bundled-plugin, коли config недійсний. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє setup-only поверхням каналу завантажуватися перед повним plugin каналу під час startup. | +| `openclaw.extensions` | Оголошує native entrypoint-и плагіна. Має залишатися всередині каталогу пакета плагіна. | +| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoint-и для встановлених пакетів. Має залишатися всередині каталогу пакета плагіна. | +| `openclaw.setupEntry` | Легкий setup-only entrypoint, що використовується під час onboarding, відкладеного запуску каналу та read-only status/SecretRef discovery каналу. Має залишатися всередині каталогу пакета плагіна. | +| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript setup entrypoint для встановлених пакетів. Потребує `setupEntry`, має існувати й залишатися всередині каталогу пакета плагіна. | +| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст вибору. | +| `openclaw.channel.commands` | Статичні native command і native skill auto-default метадані, що використовуються config, audit і command-list поверхнями до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти «чи вже існує env-only setup?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти «чи хтось уже ввійшов?» без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки install/update для вбудованих і зовнішньо опублікованих плагінів. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, з використанням semver floor на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок npm dist integrity, як-от `sha512-...`; потоки install і update перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення reinstall для вбудованого плагіна, коли config недійсний. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє setup-only поверхням каналу завантажуватися перед повним плагіном каналу під час startup. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з'являються в +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє -onboarding, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки install у `openclaw.plugin.json`. +onboarding, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих +варіантів. Не переносіть install-підказки в `openclaw.plugin.json`. `openclaw.install.minHostVersion` застосовується під час install і завантаження registry маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають -plugin на старіших hosts. +плагін на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи external catalog -мають поєднувати точні specs з `expectedIntegrity`, щоб потоки update завершувалися -fail closed, якщо отриманий npm artifact більше не відповідає закріпленому release. -Interactive onboarding усе ще пропонує довірені registry npm specs, включно з bare -package names і dist-tags, для сумісності. Діагностика catalog може +Точне pinning npm-версії вже живе в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні external catalog +entries мають поєднувати exact specs з `expectedIntegrity`, щоб update flows fail +closed, якщо отриманий npm artifact більше не відповідає pinned release. +Інтерактивний onboarding досі пропонує trusted registry npm specs, включно з bare +package names і dist-tags, для сумісності. Діагностика каталогу може розрізняти exact, floating, integrity-pinned, missing-integrity, package-name mismatch і invalid default-choice sources. Вона також попереджає, коли -`expectedIntegrity` наявний, але немає дійсного npm source, який він може закріпити. -Коли `expectedIntegrity` наявний, -потоки install/update примусово його застосовують; коли його пропущено, registry resolution +`expectedIntegrity` присутній, але немає дійсного npm source, який він може pin. +Коли `expectedIntegrity` присутній, +install/update flows enforce it; коли його omitted, registry resolution записується без integrity pin. -Plugins каналів мають надавати `openclaw.setupEntry`, коли status, список каналів -або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного -runtime. Setup entry має надавати метадані каналу плюс setup-safe config, -status і secrets adapters; тримайте network clients, Gateway listeners і -transport runtimes в основному entrypoint extension. +Плагіни каналів мають надавати `openclaw.setupEntry`, коли status, channel list +або SecretRef scans мають визначити configured accounts без завантаження повного +runtime. Setup entry має expose метадані каналу плюс setup-safe config, +status і secrets adapters; тримайте network clients, gateway listeners і +transport runtimes в основному entrypoint розширення. -Поля runtime entrypoint не перевизначають перевірки меж package для полів source -entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити -escaping шлях `openclaw.extensions` придатним до завантаження. +Поля runtime entrypoint не перевизначають перевірки меж пакета для source +entrypoint fields. Наприклад, `openclaw.runtimeExtensions` не може зробити +escaping path `openclaw.extensions` придатним до завантаження. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить -довільні broken configs installable. Наразі він лише дозволяє потокам install -відновлюватися після конкретних stale bundled-plugin upgrade failures, як-от +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не +робить довільні зламані configs installable. Сьогодні він лише дозволяє install +flows відновлюватися після конкретних stale bundled-plugin upgrade failures, таких як відсутній шлях bundled plugin або stale запис `channels.` для того самого -bundled plugin. Непов'язані помилки config усе ще блокують install і спрямовують операторів +bundled plugin. Непов’язані config errors досі block install і спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це package metadata для крихітного checker +`openclaw.channel.persistedAuthState` є метаданими пакета для крихітного checker module: ```json @@ -1082,12 +1080,12 @@ module: } ``` -Використовуйте це, коли setup, doctor, status або read-only presence flows потребують дешевого -yes/no auth probe до завантаження повного plugin каналу. Persisted auth state не є -configured channel state: не використовуйте ці метадані для auto-enable plugins, -repair runtime dependencies або визначення, чи має завантажуватися runtime каналу. -Цільовий export має бути невеликою функцією, яка читає лише persisted state; не -спрямовуйте її через повний runtime barrel каналу. +Використовуйте це, коли setup, doctor, status або read-only presence flows потребують cheap +yes/no auth probe до завантаження повного плагіна каналу. Persisted auth state не є +configured channel state: не використовуйте ці метадані, щоб auto-enable plugins, +repair runtime dependencies або вирішувати, чи має завантажуватися runtime каналу. +Цільовий export має бути невеликою function, яка читає лише persisted state; не +маршрутизуйте його через повний runtime barrel каналу. `openclaw.channel.configuredState` має таку саму форму для дешевих env-only configured checks: @@ -1106,65 +1104,64 @@ configured checks: } ``` -Використовуйте це, коли канал може відповісти про configured-state з env або інших малих -non-runtime inputs. Якщо перевірці потрібні full config resolution або реальний -runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` -plugin. +Використовуйте це, коли канал може відповісти про configured-state з env або інших tiny +non-runtime inputs. Якщо перевірка потребує full config resolution або реального +runtime каналу, тримайте цю логіку в hook плагіна `config.hasConfiguredState` +замість цього. -## Пріоритет виявлення (повторювані plugin ids) +## Пріоритет виявлення (дубльовані id плагінів) -OpenClaw виявляє plugins із кількох roots (bundled, global install, workspace, explicit config-selected paths). Якщо два виявлення мають однаковий `id`, зберігається лише **найвищопріоритетніший** маніфест; duplicates з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, workspace, явні config-selected paths). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` -2. **Bundled** — plugins, що постачаються з OpenClaw -3. **Global install** — plugins, установлені в глобальний root plugins OpenClaw -4. **Workspace** — plugins, виявлені відносно поточного workspace +1. **Config-selected** — шлях, явно pinned у `plugins.entries.` +2. **Bundled** — плагіни, що постачаються з OpenClaw +3. **Global install** — плагіни, встановлені в глобальний корінь плагінів OpenClaw +4. **Workspace** — плагіни, виявлені відносно поточного workspace Наслідки: -- Forked або stale копія bundled plugin у workspace не shadow bundled build. -- Щоб справді override bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на workspace discovery. -- Duplicate drops логуються, щоб Doctor і startup diagnostics могли вказати на discarded copy. +- Forked або stale копія bundled plugin, що лежить у workspace, не затінить bundled build. +- Щоб справді перевизначити bundled plugin локальним, pin його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладався на workspace discovery. +- Відкидання дублікатів логуються, щоб Doctor і startup diagnostics могли вказати на відкинуту копію. ## Вимоги JSON Schema -- **Кожен plugin має постачати JSON Schema**, навіть якщо він не приймає config. +- **Кожен плагін має постачати JSON Schema**, навіть якщо він не приймає config. - Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Schemas перевіряються під час читання/запису config, а не під час runtime. +- Schemas валідуються під час config read/write, а не в runtime. -## Поведінка перевірки +## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено в - маніфесті плагіна. +- Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **доступні для виявлення** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**. -- Якщо плагін встановлено, але його маніфест або схема пошкоджені чи відсутні, - перевірка не проходить, а Doctor повідомляє про помилку плагіна. -- Якщо конфігурація плагіна існує, але плагін **вимкнено**, конфігурація зберігається, а - **попередження** відображається в Doctor і журналах. + мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. +- Якщо Plugin встановлено, але його маніфест або схема пошкоджені чи відсутні, + перевірка завершується невдало, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, а + **попередження** відображається в Doctor + журналах. Повну схему `plugins.*` див. у [довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест є **обов’язковим для нативних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime все одно завантажує модуль плагіна окремо; маніфест потрібен лише для виявлення й перевірки. -- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок приймаються, якщо підсумкове значення все ще є об’єктом. -- Завантажувач маніфестів читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо плагіну вони не потрібні. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати великий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Оголошуйте ексклюзивний тип плагіна в цьому маніфесті. Runtime-поле `OpenClawPluginDefinition.kind` застаріло й залишається лише як резервна сумісність для старіших плагінів. -- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) мають лише декларативний характер. Статус, аудит, перевірка доставлення Cron та інші поверхні лише для читання все ще застосовують довіру до плагіна й політику фактичної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих runtime-майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для нативних Plugin OpenClaw**, зокрема для завантажень із локальної файлової системи. Runtime все одно завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення та перевірки. +- Нативні маніфести аналізуються за допомогою JSON5, тому коментарі, завершальні коми й ключі без лапок приймаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо Plugin вони не потрібні. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні види Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). +- Оголошуйте ексклюзивний вид Plugin у цьому маніфесті. Runtime-запис `OpenClawPluginDefinition.kind` застарів і залишається лише як резервна сумісність для старіших Plugin. +- Метадані змінних середовища (`setup.providers[].envVars`, застарілі `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Для runtime-метаданих майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з плагінами. + + Початок роботи з Plugin. Внутрішня архітектура та модель можливостей. diff --git a/docs/uk/plugins/sdk-entrypoints.md b/docs/uk/plugins/sdk-entrypoints.md index d8b76c6f7..c042779f9 100644 --- a/docs/uk/plugins/sdk-entrypoints.md +++ b/docs/uk/plugins/sdk-entrypoints.md @@ -1,24 +1,24 @@ --- read_when: - - Вам потрібен точний сигнатурний тип `definePluginEntry` або `defineChannelPluginEntry` - - Ви хочете зрозуміти режим реєстрації (повний vs налаштування vs метадані CLI) + - Вам потрібна точна сигнатура типу `definePluginEntry` або `defineChannelPluginEntry` + - Ви хочете зрозуміти режим реєстрації (повний, налаштування чи метадані CLI) - Ви шукаєте параметри точки входу sidebarTitle: Entry Points -summary: Довідка для `definePluginEntry`, `defineChannelPluginEntry` і `defineSetupPluginEntry` +summary: Довідка щодо definePluginEntry, defineChannelPluginEntry і defineSetupPluginEntry title: Точки входу Plugin x-i18n: - generated_at: "2026-04-25T02:40:27Z" - model: gpt-5.4 + generated_at: "2026-05-01T21:40:28Z" + model: gpt-5.5 provider: openai - source_hash: 8253cf0ac43ca11b42c0032027bba6e926c961b54901caaa63da70bd5ff5aab5 + source_hash: a29e7e12c38fb579bb78a0e1e753edafc43298c2795504969c3477c849a5d74d source_path: plugins/sdk-entrypoints.md - workflow: 15 + workflow: 16 --- -Кожен Plugin експортує типовий об’єкт точки входу. SDK надає три хелпери для +Кожен Plugin експортує стандартний об’єкт входу. SDK надає три допоміжні функції для їх створення. -Для встановлених Plugin `package.json` має спрямовувати завантаження під час виконання на зібраний +Для встановлених Plugins `package.json` має спрямовувати завантаження runtime на зібраний JavaScript, коли він доступний: ```json @@ -32,23 +32,30 @@ JavaScript, коли він доступний: } ``` -`extensions` і `setupEntry` залишаються валідними точками входу вихідного коду для розробки у workspace та git checkout. -`runtimeExtensions` і `runtimeSetupEntry` мають пріоритет, коли OpenClaw завантажує встановлений пакет, і дають змогу npm-пакетам уникати компіляції TypeScript під час виконання. Якщо встановлений пакет оголошує лише точку входу вихідного коду TypeScript, OpenClaw використає відповідний зібраний peer `dist/*.js`, якщо він існує, а потім повернеться до вихідного коду TypeScript. +`extensions` і `setupEntry` залишаються чинними вихідними точками входу для розробки +у workspace та git checkout. `runtimeExtensions` і `runtimeSetupEntry` є бажаними, +коли OpenClaw завантажує встановлений пакет, і дають змогу npm-пакетам уникати runtime-компіляції +TypeScript. Явні runtime-точки входу є обов’язковими: `runtimeSetupEntry` +потребує `setupEntry`, а відсутні артефакти `runtimeExtensions` або `runtimeSetupEntry` +призводять до помилки встановлення чи виявлення замість мовчазного fallback до джерела. Якщо +встановлений пакет оголошує лише вихідну точку входу TypeScript, OpenClaw використає +відповідний зібраний peer `dist/*.js`, коли він існує, а потім fallback до вихідного +TypeScript. -Усі шляхи точок входу мають залишатися в межах каталогу пакета Plugin. Точки входу під час виконання -та виведені з них peer-файли зібраного JavaScript не роблять валідним шлях `extensions` або -`setupEntry`, що виходить за межі пакета. +Усі шляхи точок входу мають залишатися всередині каталогу пакета Plugin. Runtime-точки входу +та виведені зібрані JavaScript peers не роблять чинним вихідний шлях `extensions` або +`setupEntry`, який виходить за межі пакета. - **Шукаєте покрокове пояснення?** Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових інструкцій. + **Потрібен покроковий огляд?** Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) + або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових посібників. ## `definePluginEntry` **Імпорт:** `openclaw/plugin-sdk/plugin-entry` -Для Plugin провайдерів, Plugin інструментів, Plugin хуків і всього, що **не є** +Для provider Plugins, tool Plugins, hook Plugins і всього, що **не є** каналом обміну повідомленнями. ```typescript @@ -69,27 +76,27 @@ export default definePluginEntry({ }); ``` -| Поле | Тип | Обов’язково | Типове значення | -| -------------- | ---------------------------------------------------------------- | ----------- | ------------------- | -| `id` | `string` | Так | — | -| `name` | `string` | Так | — | -| `description` | `string` | Так | — | -| `kind` | `string` | Ні | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Ні | Порожня схема об’єкта | -| `register` | `(api: OpenClawPluginApi) => void` | Так | — | +| Поле | Тип | Обов’язкове | Типово | +| ------------- | ---------------------------------------------------------------- | ----------- | ------------------------- | +| `id` | `string` | Так | — | +| `name` | `string` | Так | — | +| `description` | `string` | Так | — | +| `kind` | `string` | Ні | — | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Ні | Схема порожнього об’єкта | +| `register` | `(api: OpenClawPluginApi) => void` | Так | — | -- `id` має збігатися з вашим маніфестом `openclaw.plugin.json`. -- `kind` призначене для ексклюзивних слотів: `"memory"` або `"context-engine"`. -- `configSchema` може бути функцією для лінивого обчислення. -- OpenClaw обчислює та мемоїзує цю схему під час першого доступу, тому дорогі побудовники схем - запускаються лише один раз. +- `id` має відповідати вашому маніфесту `openclaw.plugin.json`. +- `kind` призначений для ексклюзивних слотів: `"memory"` або `"context-engine"`. +- `configSchema` може бути функцією для відкладеного обчислення. +- OpenClaw розв’язує та memoizes цю схему під час першого доступу, тому затратні побудовники схем + виконуються лише один раз. ## `defineChannelPluginEntry` **Імпорт:** `openclaw/plugin-sdk/channel-core` -Обгортає `definePluginEntry` логікою, специфічною для каналу. Автоматично викликає -`api.registerChannel({ plugin })`, відкриває необов’язковий seam метаданих CLI для кореневої довідки +Огортає `definePluginEntry` із wiring, специфічним для каналу. Автоматично викликає +`api.registerChannel({ plugin })`, надає необов’язковий seam метаданих CLI для root-help і обмежує `registerFull` режимом реєстрації. ```typescript @@ -110,48 +117,48 @@ export default defineChannelPluginEntry({ }); ``` -| Поле | Тип | Обов’язково | Типове значення | -| --------------------- | ---------------------------------------------------------------- | ----------- | ------------------- | -| `id` | `string` | Так | — | -| `name` | `string` | Так | — | -| `description` | `string` | Так | — | -| `plugin` | `ChannelPlugin` | Так | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Ні | Порожня схема об’єкта | -| `setRuntime` | `(runtime: PluginRuntime) => void` | Ні | — | -| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Ні | — | -| `registerFull` | `(api: OpenClawPluginApi) => void` | Ні | — | +| Поле | Тип | Обов’язкове | Типово | +| -------------------- | ---------------------------------------------------------------- | ----------- | ------------------------- | +| `id` | `string` | Так | — | +| `name` | `string` | Так | — | +| `description` | `string` | Так | — | +| `plugin` | `ChannelPlugin` | Так | — | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Ні | Схема порожнього об’єкта | +| `setRuntime` | `(runtime: PluginRuntime) => void` | Ні | — | +| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Ні | — | +| `registerFull` | `(api: OpenClawPluginApi) => void` | Ні | — | - `setRuntime` викликається під час реєстрації, щоб ви могли зберегти посилання на runtime - (зазвичай через `createPluginRuntimeStore`). Він пропускається під час захоплення метаданих CLI. + (зазвичай через `createPluginRuntimeStore`). Під час захоплення метаданих CLI його пропускають. - `registerCliMetadata` виконується під час `api.registrationMode === "cli-metadata"`, - `api.registrationMode === "discovery"` і + `api.registrationMode === "discovery"` та `api.registrationMode === "full"`. - Використовуйте його як канонічне місце для CLI-дескрипторів, що належать каналу, щоб коренева довідка - залишалася без активації, знімки discovery включали статичні метадані команд, а - звичайна реєстрація команд CLI залишалася сумісною з повними завантаженнями Plugin. -- Реєстрація в режимі discovery не активує, але й не є вільною від імпорту. OpenClaw може - обчислювати довірену точку входу Plugin і модуль channel Plugin, щоб побудувати - знімок, тому зберігайте імпорти верхнього рівня без побічних ефектів, а сокети, - клієнти, воркери та сервіси розміщуйте за шляхами лише для `"full"`. -- `registerFull` виконується лише коли `api.registrationMode === "full"`. Він пропускається + Використовуйте його як канонічне місце для CLI-дескрипторів, що належать каналу, щоб root help + залишалася без активації, знімки виявлення містили статичні метадані команд, а + звичайна реєстрація CLI-команд залишалася сумісною з повними завантаженнями Plugin. +- Реєстрація виявлення є неактивуючою, але не вільною від імпорту. OpenClaw може + виконати довірену точку входу Plugin і модуль channel Plugin для побудови + знімка, тому тримайте top-level imports без побічних ефектів і розміщуйте sockets, + clients, workers і services за шляхами лише для `"full"`. +- `registerFull` виконується лише коли `api.registrationMode === "full"`. Його пропускають під час завантаження лише для setup. -- Як і у `definePluginEntry`, `configSchema` може бути лінивою фабрикою, а OpenClaw - мемоїзує обчислену схему під час першого доступу. -- Для кореневих CLI-команд, що належать Plugin, віддавайте перевагу `api.registerCli(..., { descriptors: [...] })`, - якщо хочете, щоб команда залишалася ліниво завантажуваною, не зникаючи з - дерева розбору кореневого CLI. Для channel Plugin віддавайте перевагу реєстрації таких дескрипторів - із `registerCliMetadata(...)`, а `registerFull(...)` залишайте зосередженим на роботі лише під час виконання. -- Якщо `registerFull(...)` також реєструє методи Gateway RPC, залишайте їх - на префіксі, специфічному для Plugin. Зарезервовані простори імен адміністрування ядра (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) завжди примусово приводяться до +- Як і `definePluginEntry`, `configSchema` може бути відкладеною фабрикою, а OpenClaw + memoizes розв’язану схему під час першого доступу. +- Для root CLI-команд, що належать Plugin, надавайте перевагу `api.registerCli(..., { descriptors: [...] })`, + коли хочете, щоб команда залишалася lazy-loaded, не зникаючи з + дерева розбору root CLI. Для channel Plugins надавайте перевагу реєстрації цих дескрипторів + із `registerCliMetadata(...)` і тримайте `registerFull(...)` зосередженим на роботі лише runtime. +- Якщо `registerFull(...)` також реєструє методи Gateway RPC, тримайте їх на + префіксі, специфічному для Plugin. Зарезервовані core admin namespaces (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) завжди примусово переводяться в `operator.admin`. ## `defineSetupPluginEntry` **Імпорт:** `openclaw/plugin-sdk/channel-core` -Для легковагового файла `setup-entry.ts`. Повертає лише `{ plugin }` без -runtime чи CLI-логіки. +Для легкого файла `setup-entry.ts`. Повертає лише `{ plugin }` без +runtime або CLI wiring. ```typescript import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -161,24 +168,24 @@ export default defineSetupPluginEntry(myChannelPlugin); OpenClaw завантажує це замість повної точки входу, коли канал вимкнений, не налаштований або коли ввімкнене відкладене завантаження. Див. -[Setup and Config](/uk/plugins/sdk-setup#setup-entry), щоб зрозуміти, коли це має значення. +[Setup and Config](/uk/plugins/sdk-setup#setup-entry), щоб дізнатися, коли це має значення. -На практиці поєднуйте `defineSetupPluginEntry(...)` із вузькими сімействами setup-хелперів: +На практиці поєднуйте `defineSetupPluginEntry(...)` із вузькими сімействами setup helpers: -- `openclaw/plugin-sdk/setup-runtime` для безпечних для runtime setup-хелперів, таких як - адаптери setup-патчів, безпечні для імпорту, вивід lookup-note, - `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані setup-проксі -- `openclaw/plugin-sdk/channel-setup` для поверхонь setup з необов’язковим встановленням -- `openclaw/plugin-sdk/setup-tools` для CLI/archive/docs-хелперів setup/install +- `openclaw/plugin-sdk/setup-runtime` для runtime-safe setup helpers, таких як + import-safe setup patch adapters, lookup-note output, + `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані setup proxies +- `openclaw/plugin-sdk/channel-setup` для optional-install setup surfaces +- `openclaw/plugin-sdk/setup-tools` для setup/install CLI/archive/docs helpers -Тримайте важкі SDK, реєстрацію CLI та довгоживучі runtime-сервіси в повній +Тримайте важкі SDK, реєстрацію CLI та довгоживучі runtime-сервіси у повній точці входу. -Вбудовані workspace-канали, які розділяють setup- і runtime-поверхні, можуть натомість використовувати +Bundled workspace channels, які розділяють setup і runtime surfaces, можуть натомість використовувати `defineBundledChannelSetupEntry(...)` з -`openclaw/plugin-sdk/channel-entry-contract`. Цей контракт дає змогу -точці входу setup зберігати безпечні для setup експорти plugin/secrets, водночас відкриваючи -setter runtime: +`openclaw/plugin-sdk/channel-entry-contract`. Цей contract дає setup entry змогу +зберігати setup-safe plugin/secrets exports, водночас усе ще надаючи +runtime setter: ```typescript import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract"; @@ -196,23 +203,23 @@ export default defineBundledChannelSetupEntry({ }); ``` -Використовуйте цей вбудований контракт лише тоді, коли setup-потокам справді потрібен легковаговий -setter runtime до завантаження повної точки входу каналу. +Використовуйте цей bundled contract лише тоді, коли setup flows справді потребують легкого runtime +setter до завантаження повної точки входу каналу. ## Режим реєстрації -`api.registrationMode` повідомляє вашому Plugin, як саме його було завантажено: +`api.registrationMode` повідомляє вашому Plugin, як його було завантажено: -| Режим | Коли | Що реєструвати | -| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `"full"` | Звичайний запуск Gateway | Усе | -| `"discovery"` | Discovery можливостей лише для читання | Реєстрація каналу плюс статичні CLI-дескриптори; код точки входу може завантажуватися, але пропускайте сокети, воркери, клієнти та сервіси | -| `"setup-only"` | Вимкнений/неналаштований канал | Лише реєстрація каналу | -| `"setup-runtime"` | Потік setup з доступним runtime | Реєстрація каналу плюс лише легковаговий runtime, потрібний до завантаження повної точки входу | -| `"cli-metadata"` | Коренева довідка / захоплення метаданих CLI | Лише CLI-дескриптори | +| Режим | Коли | Що реєструвати | +| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `"full"` | Звичайний запуск Gateway | Усе | +| `"discovery"` | Read-only capability discovery | Реєстрація каналу плюс статичні CLI-дескриптори; код точки входу може завантажуватися, але пропускайте sockets, workers, clients і services | +| `"setup-only"` | Вимкнений/неналаштований канал | Лише реєстрація каналу | +| `"setup-runtime"` | Setup flow з доступним runtime | Реєстрація каналу плюс лише легкий runtime, потрібний до завантаження повної точки входу | +| `"cli-metadata"` | Root help / захоплення метаданих CLI | Лише CLI-дескриптори | `defineChannelPluginEntry` обробляє цей поділ автоматично. Якщо ви використовуєте -`definePluginEntry` безпосередньо для каналу, самі перевіряйте режим: +`definePluginEntry` безпосередньо для каналу, перевіряйте режим самостійно: ```typescript register(api) { @@ -233,47 +240,48 @@ register(api) { } ``` -Режим discovery будує знімок реєстру без активації. Він усе ж може обчислювати -точку входу Plugin і об’єкт channel Plugin, щоб OpenClaw міг зареєструвати можливості каналу -та статичні CLI-дескриптори. Ставтеся до обчислення модуля в discovery як до -довіреного, але легковагового: без мережевих клієнтів, підпроцесів, слухачів, з’єднань із базою даних, -фонових воркерів, читання облікових даних чи інших побічних ефектів живого runtime на верхньому рівні. +Режим discovery будує неактивуючий знімок реєстру. Він все ще може виконати +точку входу Plugin і об’єкт channel Plugin, щоб OpenClaw міг зареєструвати +можливості каналу та статичні CLI-дескриптори. Ставтеся до виконання модуля в discovery як до +довіреного, але легкого: жодних network clients, subprocesses, listeners, database +connections, background workers, credential reads або інших live runtime side +effects на top level. -Сприймайте `"setup-runtime"` як вікно, у якому поверхні запуску лише для setup мають -існувати без повторного входу в повний bundled runtime каналу. Добре підходять -реєстрація каналу, безпечні для setup HTTP-маршрути, безпечні для setup методи Gateway -і делеговані setup-хелпери. Важкі фонові сервіси, реєстратори CLI -та завантаження SDK провайдерів/клієнтів усе ще належать до `"full"`. +Сприймайте `"setup-runtime"` як вікно, у якому setup-only startup surfaces мають +існувати без повторного входу в повний bundled channel runtime. Добре підходять +реєстрація каналу, setup-safe HTTP routes, setup-safe Gateway methods і +делеговані setup helpers. Важкі background services, CLI registrars і +provider/client SDK bootstraps усе ще належать до `"full"`. -Зокрема для реєстраторів CLI: +Для CLI registrars зокрема: -- використовуйте `descriptors`, коли реєстратор володіє однією чи кількома кореневими командами і ви - хочете, щоб OpenClaw ліниво завантажував справжній модуль CLI під час першого виклику -- переконайтеся, що ці дескриптори охоплюють кожен корінь команди верхнього рівня, який відкриває - реєстратор -- імена команд дескрипторів мають містити лише літери, цифри, дефіс і підкреслення, - починаючись із літери або цифри; OpenClaw відхиляє імена дескрипторів поза - цією формою та прибирає керувальні послідовності термінала з описів перед - показом довідки -- використовуйте лише `commands` тільки для eager-шляхів сумісності +- використовуйте `descriptors`, коли registrar володіє однією чи кількома root-командами і ви + хочете, щоб OpenClaw lazy-load реальний CLI-модуль під час першого виклику +- переконайтеся, що ці descriptors покривають кожен root top-level command, який надає + registrar +- обмежуйте імена команд descriptors літерами, цифрами, дефісом і підкресленням, + починаючи з літери або цифри; OpenClaw відхиляє імена descriptors поза + цією формою та видаляє terminal control sequences з описів перед + відтворенням help +- використовуйте лише `commands` тільки для eager compatibility paths ## Форми Plugin -OpenClaw класифікує завантажені Plugin за їхньою поведінкою реєстрації: +OpenClaw класифікує завантажені плагіни за їхньою поведінкою реєстрації: | Форма | Опис | | --------------------- | -------------------------------------------------- | -| **plain-capability** | Один тип можливостей (наприклад, лише провайдер) | -| **hybrid-capability** | Кілька типів можливостей (наприклад, провайдер + мовлення) | -| **hook-only** | Лише хуки, без можливостей | -| **non-capability** | Інструменти/команди/сервіси, але без можливостей | +| **plain-capability** | Один тип можливості (наприклад, лише provider) | +| **hybrid-capability** | Кілька типів можливостей (наприклад, provider + speech) | +| **hook-only** | Лише hooks, без можливостей | +| **non-capability** | Tools/commands/services, але без можливостей | -Використовуйте `openclaw plugins inspect `, щоб побачити форму Plugin. +Використовуйте `openclaw plugins inspect `, щоб переглянути форму плагіна. ## Пов’язане -- [SDK Overview](/uk/plugins/sdk-overview) — API реєстрації та довідка щодо subpath -- [Runtime Helpers](/uk/plugins/sdk-runtime) — `api.runtime` і `createPluginRuntimeStore` -- [Setup and Config](/uk/plugins/sdk-setup) — маніфест, точка входу setup, відкладене завантаження -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — побудова об’єкта `ChannelPlugin` -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — реєстрація провайдера та хуки +- [Огляд SDK](/uk/plugins/sdk-overview) — API реєстрації та довідник subpath +- [Допоміжні засоби Runtime](/uk/plugins/sdk-runtime) — `api.runtime` і `createPluginRuntimeStore` +- [Налаштування та конфігурація](/uk/plugins/sdk-setup) — manifest, setup entry, відкладене завантаження +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення об’єкта `ChannelPlugin` +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — реєстрація provider і hooks diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index 9dd801917..e89334142 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,27 +1,26 @@ --- read_when: - Встановлення або налаштування плагінів - - Розуміння правил виявлення й завантаження Plugin + - Розуміння правил виявлення та завантаження Plugin - Робота з пакетами Plugin, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлення, налаштування та керування плагінами OpenClaw +summary: Встановлення, налаштування та керування Plugin OpenClaw title: Plugins x-i18n: - generated_at: "2026-05-01T21:00:17Z" + generated_at: "2026-05-01T21:40:38Z" model: gpt-5.5 provider: openai - source_hash: 32e89479c899f05756ba2853728ff9428e1b0ef866d336bba721a962f5546a8b + source_hash: 0dbb4d0102f3f2060fe13aa5e6ae1b24080a456f223e985ccfa390106e94f4d8 source_path: tools/plugin.md workflow: 16 --- -Plugin розширюють OpenClaw новими можливостями: канали, постачальники моделей, -оболонки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, -голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, -отримання вебданих, вебпошук тощо. Деякі Plugin є **основними** (постачаються з OpenClaw), інші -є **зовнішніми**. Більшість зовнішніх Plugin публікуються та знаходяться через -[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для -тимчасового набору пакетів Plugin, що належать OpenClaw, доки ця міграція завершується. +Plugin-и розширюють OpenClaw новими можливостями: каналами, провайдерами моделей, +обв’язками агентів, інструментами, Skills, мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, отриманням вебвмісту, вебпошуком +і не тільки. Деякі Plugin-и є **core** (постачаються з OpenClaw), інші +є **зовнішніми**. Більшість зовнішніх Plugin-ів публікуються й знаходяться через +[ClawHub](/uk/tools/clawhub). Npm і надалі підтримується для прямих встановлень і для +тимчасового набору пакетів Plugin-ів, що належать OpenClaw, доки ця міграція завершується. ## Швидкий старт @@ -32,7 +31,7 @@ Plugin розширюють OpenClaw новими можливостями: ка ``` - + ```bash # From npm openclaw plugins install npm:@acme/openclaw-plugin @@ -52,7 +51,7 @@ Plugin розширюють OpenClaw новими можливостями: ка openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому конфігураційному файлі. + Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. @@ -64,9 +63,9 @@ Plugin розширюють OpenClaw новими можливостями: ка openclaw --help ``` - Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, служби, gateway - методи, хуки або CLI-команди, що належать Plugin. Звичайний `inspect` є холодною - перевіркою маніфесту/реєстру й навмисно не імпортує runtime Plugin. + Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, сервіси, gateway + методи, хуки або CLI-команди, що належать Plugin-у. Звичайний `inspect` — це холодна + перевірка маніфесту/реєстру, яка навмисно уникає імпортування runtime Plugin-а. @@ -79,65 +78,65 @@ Plugin розширюють OpenClaw новими можливостями: ка /plugin enable ``` -Шлях встановлення використовує той самий розв’язувач, що й CLI: локальний шлях/архів, явний -`clawhub:`, явний `npm:`, явний `git:` або проста специфікація пакета -(спочатку ClawHub, потім запасний варіант npm). +Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний +`clawhub:`, явний `npm:`, явний `git:` або просту специфікацію пакета +(спочатку ClawHub, потім резервно npm). -Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується помилкою і скеровує вас до -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях -перевстановлення вбудованих Plugin для Plugin, які погоджуються на +Якщо конфігурація недійсна, встановлення зазвичай завершується без змін і спрямовує вас до +`openclaw doctor --fix`. Єдиний виняток відновлення — вузький шлях перевстановлення вбудованого Plugin-а для Plugin-ів, які увімкнули `openclaw.install.allowInvalidConfigRecovery`. -Під час запуску Gateway недійсна конфігурація одного Plugin ізолюється до цього Plugin: -запуск записує в журнали проблему `plugins.entries..config`, пропускає цей Plugin під час -завантаження й залишає інші Plugin та канали онлайн. Запустіть `openclaw doctor --fix`, -щоб помістити погану конфігурацію Plugin у карантин, вимкнувши цей запис Plugin і видаливши -його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на Plugin, який більше не вдається знайти, але той самий -застарілий ідентифікатор Plugin залишається в конфігурації Plugin або записах встановлення, запуск Gateway -записує попередження в журнали й пропускає цей канал замість блокування всіх інших каналів. -Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/Plugin; невідомі -ключі каналів без доказів застарілого Plugin все одно не проходять валідацію, щоб помилки введення залишалися -видимими. -Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugin вважаються інертними: -запуск Gateway пропускає роботу з виявлення/завантаження Plugin, а `openclaw doctor` зберігає -вимкнену конфігурацію Plugin замість автоматичного видалення. Повторно увімкніть Plugin перед -запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори Plugin. +Під час запуску Gateway недійсна конфігурація одного Plugin-а ізолюється до цього Plugin-а: +запуск журналює проблему `plugins.entries..config`, пропускає цей Plugin під час +завантаження та залишає інші Plugin-и й канали онлайн. Запустіть `openclaw doctor --fix`, +щоб помістити проблемну конфігурацію Plugin-а в карантин, вимкнувши цей запис Plugin-а й вилучивши +його недійсний конфігураційний payload; звичайна резервна копія конфігурації зберігає попередні значення. +Коли конфігурація каналу посилається на Plugin, який більше не виявляється, але той самий застарілий id Plugin-а залишається в конфігурації Plugin-ів або записах встановлення, запуск Gateway +журналює попередження й пропускає цей канал замість блокування всіх інших каналів. +Запустіть `openclaw doctor --fix`, щоб вилучити застарілі записи каналу/Plugin-а; невідомі +ключі каналів без ознак застарілого Plugin-а й надалі не проходять валідацію, щоб друкарські помилки залишалися +помітними. +Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugin-и вважаються інертними: +запуск Gateway пропускає виявлення/завантаження Plugin-ів, а `openclaw doctor` зберігає +вимкнену конфігурацію Plugin-ів замість автоматичного вилучення. Знову ввімкніть Plugin-и перед +запуском очищення doctor, якщо хочете вилучити застарілі id Plugin-ів. -Встановлення залежностей Plugin відбувається лише під час явних потоків встановлення/оновлення або -відновлення doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція не -запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні Plugin уже повинні -мати встановлені залежності, тоді як npm, git і ClawHub Plugin -встановлюються під керованими коренями Plugin OpenClaw із локальними для пакета -залежностями. Зовнішні Plugin і користувацькі шляхи завантаження все одно мають встановлюватися +Встановлення залежностей Plugin-а відбувається лише під час явних потоків install/update або +doctor repair. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція не +запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні Plugin-и вже повинні +мати встановлені залежності, тоді як npm, git і ClawHub Plugin-и +встановлюються в керовані корені Plugin-ів OpenClaw із локальними для пакета +залежностями. Зовнішні Plugin-и та власні шляхи завантаження все одно потрібно встановлювати через `openclaw plugins install`. -Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) для життєвого циклу -під час встановлення. +Див. [Розв’язання залежностей Plugin-а](/uk/plugins/dependency-resolution) щодо +життєвого циклу під час встановлення. -## Типи Plugin +## Типи Plugin-ів -OpenClaw розпізнає два формати Plugin: +OpenClaw розпізнає два формати Plugin-ів: | Формат | Як це працює | Приклади | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні Plugin, пакети npm спільноти | -| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні Plugin-и, community npm-пакети | +| **Bundle** | Макет, сумісний із Codex/Claude/Cursor; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва з’являються в `openclaw plugins list`. Див. [Пакети Plugin](/uk/plugins/bundles) для деталей пакетів. +Обидва відображаються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) щодо деталей bundle. -Якщо ви пишете нативний Plugin, почніть із [Створення Plugin](/uk/plugins/building-plugins) -і [Огляд Plugin SDK](/uk/plugins/sdk-overview). +Якщо ви пишете native Plugin, почніть із [Створення Plugin-ів](/uk/plugins/building-plugins) +і [Огляду Plugin SDK](/uk/plugins/sdk-overview). -## Точки входу пакета +## Точки входу пакетів -Пакети npm нативних Plugin мають оголошувати `openclaw.extensions` у `package.json`. -Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в читабельний -runtime-файл або в початковий файл TypeScript з виведеним зібраним JavaScript -парним файлом, наприклад `src/index.ts` до `dist/index.js`. +Npm-пакети native Plugin-ів мають оголошувати `openclaw.extensions` у `package.json`. +Кожен запис має залишатися всередині директорії пакета й резолвитися в читабельний +runtime-файл або у TypeScript-файл вихідного коду з виведеним побудованим JavaScript +відповідником, як-от `src/index.ts` до `dist/index.js`. Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за -тими самими шляхами, що й початкові записи. Коли `runtimeExtensions` присутній, він має містити -рівно один запис для кожного запису `extensions`. Невідповідні списки спричиняють помилку встановлення та -виявлення Plugin замість тихого повернення до початкових шляхів. +тими самими шляхами, що й вихідні записи. За наявності `runtimeExtensions` має містити +рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення та +виявлення Plugin-а замість тихого відкату до шляхів вихідного коду. Якщо ви також +публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його побудованого +JavaScript-відповідника; цей файл є обов’язковим, якщо оголошений. ```json { @@ -149,19 +148,19 @@ runtime-файл або в початковий файл TypeScript з виве } ``` -## Офіційні Plugin +## Офіційні Plugin-и ### Npm-пакети, що належать OpenClaw, під час міграції -ClawHub є основним шляхом розповсюдження для більшості Plugin. Поточні упаковані -релізи OpenClaw уже містять багато офіційних Plugin, тож у звичайних налаштуваннях для них не потрібні -окремі npm-встановлення. Доки кожен Plugin, що належить OpenClaw, не -мігрує до ClawHub, OpenClaw все ще постачає деякі пакети Plugin `@openclaw/*` в -npm для старіших/користувацьких встановлень і прямих npm-процесів. +ClawHub є основним шляхом розповсюдження для більшості Plugin-ів. Поточні пакетовані +релізи OpenClaw вже містять багато офіційних Plugin-ів, тож вони не потребують +окремих npm-встановлень у звичайних налаштуваннях. Доки кожен Plugin, що належить OpenClaw, не +мігрував до ClawHub, OpenClaw і надалі постачає деякі пакети Plugin-ів `@openclaw/*` в +npm для старіших/власних встановлень і прямих npm-процесів. -Якщо npm повідомляє, що пакет Plugin `@openclaw/*` є застарілим, ця версія пакета -походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований Plugin із -поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. +Якщо npm повідомляє, що пакет Plugin-а `@openclaw/*` застарілий, ця версія пакета +походить зі старішої зовнішньої лінійки пакетів. Використовуйте вбудований Plugin із +поточного OpenClaw або локальний checkout, доки новіший npm-пакет не буде опубліковано. | Plugin | Пакет | Документація | | --------------- | -------------------------- | ------------------------------------------ | @@ -179,10 +178,10 @@ npm для старіших/користувацьких встановлень | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Основні (постачаються з OpenClaw) +### Core (постачається з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -190,27 +189,27 @@ npm для старіших/користувацьких встановлень `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`) + + - `memory-core` — вбудований пошук memory (за замовчуванням через `plugins.slots.memory`) + - `memory-lancedb` — довготривала memory на базі LanceDB з auto-recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`) - Див. [Memory LanceDB](/uk/plugins/memory-lancedb) для налаштування - OpenAI-сумісних embeddings, прикладів Ollama, обмежень пригадування та усунення несправностей. + Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо OpenAI-сумісного + налаштування embeddings, прикладів Ollama, лімітів recall і усунення несправностей. - + `elevenlabs`, `microsoft` - - `browser` — вбудований Plugin браузера для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, runtime браузера та служби керування браузером за замовчуванням (увімкнено за замовчуванням; вимкніть перед заміною) + - `browser` — вбудований browser Plugin для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартного сервісу керування браузером (увімкнено за замовчуванням; вимкніть перед заміною) - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням) -Шукаєте сторонні Plugin? Див. [Plugin спільноти](/uk/plugins/community). +Шукаєте сторонні Plugin-и? Див. [Community Plugins](/uk/plugins/community). ## Конфігурація @@ -231,115 +230,114 @@ npm для старіших/користувацьких встановлень | Поле | Опис | | ---------------- | --------------------------------------------------------- | | `enabled` | Головний перемикач (за замовчуванням: `true`) | -| `allow` | Allowlist Plugin (необов’язково) | -| `deny` | Denylist Plugin (необов’язково; deny має перевагу) | -| `load.paths` | Додаткові файли/каталоги Plugin | +| `allow` | Allowlist Plugin-ів (необов’язково) | +| `deny` | Denylist Plugin-ів (необов’язково; deny має пріоритет) | +| `load.paths` | Додаткові файли/директорії Plugin-ів | | `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі + конфігурація для окремих Plugin | +| `entries.\` | Перемикачі + конфігурація для окремого Plugin-а | `plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися або -відкривати інструменти можуть лише перелічені Plugin, навіть якщо `tools.allow` містить `"*"` або конкретну назву -інструмента, що належить Plugin. Якщо allowlist інструментів посилається на інструменти Plugin, додайте ідентифікатори Plugin-власників -до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку +надавати інструменти можуть лише перелічені Plugin-и, навіть якщо `tools.allow` містить `"*"` або конкретну назву +інструмента, що належить Plugin-у. Якщо allowlist інструментів посилається на інструменти Plugin-ів, додайте id Plugin-ів-власників +до `plugins.allow` або вилучіть `plugins.allow`; `openclaw doctor` попереджає про таку форму. -Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими -спостереженням за конфігурацією та перезапуском у процесі (стандартний шлях `openclaw gateway`), цей -перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. -Підтримуваного шляху гарячого перезавантаження для runtime-коду нативного Plugin або lifecycle -хуків немає; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж -очікувати виконання оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, служб або -provider/runtime хуків. +Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими config +watch + in-process restart (стандартний шлях `openclaw gateway`), такий +перезапуск зазвичай виконується автоматично за мить після запису конфігурації. +Немає підтримуваного шляху hot-reload для runtime-коду native Plugin-а або lifecycle +hooks; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж +очікувати запуску оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, сервісів або +provider/runtime hooks. -`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. Позначений там як -`enabled` Plugin означає, що збережений реєстр і поточна конфігурація дозволяють -Plugin брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway -перезапустився з тим самим кодом Plugin. У VPS/container налаштуваннях з +`openclaw plugins list` — це локальний snapshot реєстру/конфігурації Plugin-ів. Plugin зі станом +`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють +Plugin-у брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway +перезапустився з тим самим кодом Plugin-а. У налаштуваннях VPS/контейнерів із процесами-обгортками надсилайте перезапуски фактичному процесу `openclaw gateway run` або використовуйте `openclaw gateway restart` для запущеного Gateway. - - - **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. - - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який виявлення не знайшло. - - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши його конфігураційне навантаження. + + - **Вимкнений**: Plugin існує, але правила ввімкнення вимкнули його. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на id Plugin-а, який discovery не знайшов. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його й вилучивши його конфігураційний payload. ## Виявлення та пріоритетність -OpenClaw сканує Plugin у такому порядку (перша відповідність перемагає): +OpenClaw сканує plugins у такому порядку (перше співпадіння перемагає): - `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують - назад на власні каталоги пакетних вбудованих Plugin OpenClaw, ігноруються; - виконайте `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. + `plugins.load.paths` — явні шляхи до файлів або директорій. Шляхи, що вказують + назад на власні упаковані директорії bundled plugin OpenClaw, ігноруються; + запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення). + + Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). Інші потребують явного ввімкнення. -Пакетні встановлення та образи Docker зазвичай знаходять вбудовані Plugin у -скомпільованому дереві `dist/extensions`. Якщо вихідний каталог вбудованого Plugin -змонтовано поверх відповідного пакетного шляху до вихідного коду, наприклад -`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог -як накладання вбудованого вихідного коду й виявляє його перед пакетним бандлом +Упаковані встановлення та Docker-образи зазвичай розв’язують bundled plugins з +скомпільованого дерева `dist/extensions`. Якщо директорію джерел bundled plugin +змонтовано bind mount поверх відповідного упакованого шляху джерел, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цю змонтовану директорію +джерел як bundled source overlay і виявляє її перед упакованим бандлом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних -циклів супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. -Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати пакетні dist-бандли -навіть за наявності монтувань накладання вихідного коду. +циклів супровідників без перемикання кожного bundled plugin назад на джерела TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово +використовувати упаковані dist-бандли, навіть коли наявні source overlay mounts. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі Plugin і пропускає роботу з виявлення/завантаження Plugin +- `plugins.enabled: false` вимикає всі plugins і пропускає роботу виявлення/завантаження Plugin - `plugins.deny` завжди має пріоритет над allow - `plugins.entries.\.enabled: false` вимикає цей Plugin -- Plugin, що походять із робочого простору, **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) -- Вбудовані Plugin дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено +- Plugins з походженням workspace **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Bundled plugins дотримуються вбудованого набору default-on, якщо його не перевизначено - Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота -- Деякі вбудовані Plugin з явним підключенням автоматично вмикаються, коли конфігурація називає - поверхню, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або runtime - тестового середовища -- Застаріла конфігурація Plugin зберігається, поки активне `plugins.enabled: false`; - повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете видалити застарілі ids +- Деякі bundled opt-in plugins вмикаються автоматично, коли конфігурація називає + surface, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або runtime harness +- Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`; + повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі id - Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: - `openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin app-server Codex - вибирається через `agentRuntime.id: "codex"` або застарілі посилання на моделі - `codex/*` + `openai-codex/*` належить OpenAI plugin, тоді як bundled Codex + app-server plugin вибирається через `agentRuntime.id: "codex"` або legacy + посилання на моделі `codex/*` -## Усунення проблем runtime hooks +## Усунення несправностей runtime hooks -Якщо Plugin з’являється в `plugins list`, але побічні ефекти або hooks -`register(api)` не виконуються в живому чат-трафіку, спершу перевірте це: +Якщо Plugin з’являється у `plugins list`, але побічні ефекти або hooks +`register(api)` не запускаються в live chat traffic, спочатку перевірте це: -- Виконайте `openclaw gateway status --deep --require-rpc` і переконайтеся, що активні +- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте. -- Перезапустіть живий Gateway після встановлення Plugin або змін конфігурації/коду. У wrapper - контейнерах PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому +- Перезапустіть live Gateway після змін встановлення/конфігурації/коду Plugin. У wrapper + containers PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використовуйте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hook і - діагностику. Невбудовані conversation hooks, як-от `llm_input`, +- Використовуйте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hooks і + діагностику. Non-bundled conversation hooks, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`, потребують `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до розв’язання моделі - для ходів агента; `llm_output` виконується лише після того, як спроба моделі - створить вивід асистента. -- Для підтвердження ефективної моделі сеансу використовуйте `openclaw sessions` або - поверхні сеансів/статусу Gateway, а під час налагодження payload провайдера запускайте +- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед + розв’язанням моделі для agent turns; `llm_output` запускається лише після того, як спроба моделі + створить assistant output. +- Для підтвердження фактичної моделі сесії використовуйте `openclaw sessions` або + поверхні сесії/статусу Gateway, а під час налагодження provider payloads запускайте Gateway з `--raw-stream --raw-stream-path `. -### Дублювання володіння каналом або інструментом +### Дублювання власності каналу або інструмента Симптоми: @@ -348,33 +346,33 @@ OpenClaw сканує Plugin у такому порядку (перша відп - `plugin tool name conflict (): ` Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, -потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, -встановлений поруч із вбудованим Plugin, який тепер надає той самий id каналу. +потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній channel plugin, +встановлений поруч із bundled plugin, який тепер надає той самий channel id. Кроки налагодження: -- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin +- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin і його походження. -- Виконайте `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і +- Запустіть `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і порівняйте `channels`, `channelConfigs`, `tools` і діагностику. -- Виконайте `openclaw plugins registry --refresh` після встановлення або видалення - пакетів Plugin, щоб збережені метадані відображали поточне встановлення. -- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації. +- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення + plugin packages, щоб збережені metadata відображали поточне встановлення. +- Перезапустіть Gateway після змін встановлення, registry або конфігурації. Варіанти виправлення: -- Якщо один Plugin навмисно замінює інший для того самого id каналу, бажаний - Plugin має оголосити `channelConfigs..preferOver` з id Plugin - нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). +- Якщо один Plugin навмисно замінює інший для того самого channel id, бажаний + Plugin має оголосити `channelConfigs..preferOver` з + нижчопріоритетним plugin id. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). - Якщо дублювання випадкове, вимкніть одну сторону через `plugins.entries..enabled: false` або видаліть застаріле встановлення Plugin. -- Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і +- Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, - що належать Plugin, щоб runtime-поверхня була однозначною. + що належать Plugin, щоб runtime surface була однозначною. ## Слоти Plugin (ексклюзивні категорії) -Деякі категорії є ексклюзивними (одночасно активна лише одна): +Деякі категорії є ексклюзивними (активною може бути лише одна за раз): ```json5 { @@ -387,10 +385,10 @@ OpenClaw сканує Plugin у такому порядку (перша відп } ``` -| Слот | Що він контролює | За замовчуванням | -| --------------- | ----------------------- | ------------------ | -| `memory` | Plugin Active memory | `memory-core` | -| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | +| Слот | Що він контролює | За замовчуванням | +| --------------- | --------------------- | ------------------- | +| `memory` | Plugin active memory | `memory-core` | +| `contextEngine` | Активний context engine | `legacy` (вбудований) | ## Довідник CLI @@ -439,80 +437,79 @@ openclaw plugins enable openclaw plugins disable ``` -Вбудовані Plugin постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад -вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний -Plugin). Інші вбудовані Plugin все ще потребують `openclaw plugins enable `. +Bundled plugins постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад +bundled model providers, bundled speech providers і bundled browser +plugin). Інші bundled plugins все ще потребують `openclaw plugins enable `. `--force` перезаписує наявний встановлений Plugin або hook pack на місці. Використовуйте -`openclaw plugins update ` для звичайних оновлень відстежуваних npm -Plugin. Він не підтримується з `--link`, який повторно використовує шлях до вихідного коду замість -копіювання в керовану ціль встановлення. +`openclaw plugins update ` для регулярних оновлень відстежуваних npm +plugins. Це не підтримується з `--link`, який повторно використовує шлях джерел замість +копіювання поверх керованої цілі встановлення. Коли `plugins.allow` уже задано, `openclaw plugins install` додає id -встановленого Plugin до цього allowlist перед його ввімкненням. Якщо той самий id Plugin -присутній у `plugins.deny`, встановлення видаляє цей застарілий запис deny, щоб -явне встановлення можна було завантажити одразу після перезапуску. +встановленого Plugin до цього allowlist перед його ввімкненням. Якщо той самий plugin id +присутній у `plugins.deny`, install видаляє цей застарілий запис deny, щоб +явне встановлення можна було одразу завантажити після перезапуску. -OpenClaw зберігає локальний реєстр Plugin як холодну модель читання для -інвентаризації Plugin, володіння внесками та планування запуску. Потоки встановлення, оновлення, -видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану Plugin. -Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у -верхньорівневих `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо -реєстр відсутній, застарілий або недійсний, `openclaw plugins registry ---refresh` перебудовує його представлення маніфестів із записів встановлення, політики конфігурації та -метаданих manifest/package без завантаження runtime-модулів Plugin. +OpenClaw зберігає persistent local plugin registry як cold read model для +інвентаризації Plugin, власності contributions і планування запуску. Потоки install, update, +uninstall, enable і disable оновлюють цей registry після зміни стану Plugin. +Той самий файл `plugins/installs.json` зберігає довговічні install metadata у +top-level `installRecords` і перебудовувані manifest metadata у `plugins`. Якщо +registry відсутній, застарілий або недійсний, `openclaw plugins registry +--refresh` перебудовує його manifest view з install records, config policy і +manifest/package metadata без завантаження runtime modules Plugin. `openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -npm package spec із dist-tag або точною версією розв’язує назву пакета +npm package spec з dist-tag або точною версією розв’язує package name назад до відстежуваного запису Plugin і записує новий spec для майбутніх оновлень. -Передавання назви пакета без версії повертає точно pinned встановлення назад до -типової release line реєстру. Якщо встановлений npm Plugin уже відповідає +Передавання package name без версії переводить exact pinned install назад на +лінію релізів за замовчуванням registry. Якщо встановлений npm plugin уже відповідає розв’язаній версії та записаній ідентичності артефакта, OpenClaw пропускає оновлення -без завантаження, повторного встановлення або переписування конфігурації. +без завантаження, перевстановлення або перезапису конфігурації. -`--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки -встановлення з marketplace зберігають метадані джерела marketplace замість npm spec. +`--pin` є лише для npm. Він не підтримується з `--marketplace`, тому що +marketplace installs зберігають metadata джерела marketplace замість npm spec. -`--dangerously-force-unsafe-install` — аварійне перевизначення для хибнопозитивних -спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановлення Plugin +`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних +спрацювань вбудованого dangerous-code scanner. Воно дозволяє встановлення Plugin і оновлення Plugin продовжуватися попри вбудовані findings рівня `critical`, але все одно -не обходить блокування політики Plugin `before_install` або блокування через помилку сканування. -Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`, -`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати пакетні test mocks; -оголошені runtime-точки входу Plugin все одно скануються, навіть якщо вони використовують одну з +не обходить блокування plugin `before_install` policy або блокування через scan-failure. +Install scans ігнорують типові тестові файли та директорії, як-от `tests/`, +`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати packaged test mocks; +оголошені runtime entrypoints Plugin усе одно скануються, навіть якщо вони використовують одну з цих назв. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Встановлення -залежностей skill на основі Gateway натомість використовують відповідне перевизначення запиту +Цей CLI flag застосовується лише до потоків install/update Plugin. Встановлення skill +dependencies через Gateway використовують відповідне override запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком -завантаження/встановлення skill із ClawHub. +завантаження/встановлення Skills з ClawHub. -Якщо Plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте -панель ClawHub або виконайте `clawhub package rescan `, щоб попросити ClawHub перевірити -його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій власній -машині; він не просить ClawHub повторно сканувати Plugin або робити заблокований release +Якщо Plugin, який ви опублікували на ClawHub, прихований або заблокований скануванням, відкрийте +dashboard ClawHub або запустіть `clawhub package rescan `, щоб попросити ClawHub перевірити +його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному +комп’ютері; він не просить ClawHub повторно сканувати Plugin або робити заблокований реліз публічним. -Сумісні бандли беруть участь у тому самому потоці list/inspect/enable/disable -для Plugin. Поточна підтримка runtime включає bundle skills, Claude command-skills, -стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` і оголошені в маніфесті -`lspServers`, Cursor command-skills і сумісні каталоги hook Codex. +Сумісні бандли беруть участь у тому самому потоці list/inspect/enable/disable для Plugin. +Поточна підтримка runtime включає bundle skills, Claude command-skills, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і manifest-declared +`lspServers`, Cursor command-skills і сумісні директорії Codex hooks. -`openclaw plugins inspect ` також повідомляє виявлені можливості бандла, а також -підтримувані або непідтримувані записи серверів MCP і LSP для Plugin на основі бандлів. +`openclaw plugins inspect ` також повідомляє виявлені можливості bundle, а також +підтримувані або непідтримувані записи серверів MCP і LSP для bundle-backed plugins. -Джерелами маркетплейсу можуть бути відома назва маркетплейсу Claude з +Джерелами маркетплейсу можуть бути відома Claude назва маркетплейсу з `~/.claude/plugins/known_marketplaces.json`, локальний корінь маркетплейсу або -шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL -репозиторію GitHub або git URL. Для віддалених маркетплейсів записи Plugin -мають залишатися всередині клонованого репозиторію маркетплейсу та використовувати -лише відносні джерела шляхів. +шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію +GitHub або git URL. Для віддалених маркетплейсів записи плагінів мають залишатися всередині +клонованого репозиторію маркетплейсу й використовувати лише відносні джерела шляхів. -Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins). +Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins). ## Огляд API Plugin -Нативні Plugin експортують об'єкт входу, який надає `register(api)`. Старіші -Plugin можуть усе ще використовувати `activate(api)` як застарілий псевдонім, але нові Plugin мають +Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші +плагіни можуть іще використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають використовувати `register`. ```typescript @@ -533,29 +530,29 @@ export default definePluginEntry({ }); ``` -OpenClaw завантажує об'єкт входу та викликає `register(api)` під час -активації Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugin, -але вбудовані Plugin і нові зовнішні Plugin мають розглядати `register` як +OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації плагіна. +Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, +але вбудовані плагіни й нові зовнішні плагіни мають розглядати `register` як публічний контракт. -`api.registrationMode` повідомляє Plugin, чому його вхід завантажується: +`api.registrationMode` повідомляє плагіну, чому завантажується його вхід: -| Режим | Значення | +| Режим | Значення | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація в середовищі виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | -| `discovery` | Доступне лише для читання виявлення можливостей. Реєструйте провайдерів і метадані; довірений код входу Plugin може завантажуватися, але пропускайте активні побічні ефекти. | -| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. | -| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | -| `cli-metadata` | Лише збирання метаданих команд CLI. | +| `full` | Активація під час виконання. Реєструє інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | +| `discovery` | Доступне лише для читання виявлення можливостей. Реєструє провайдерів і метадані; довірений код входу плагіна може завантажуватися, але активні побічні ефекти слід пропускати. | +| `setup-only` | Завантаження метаданих налаштування каналу через легковаговий вхід налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід часу виконання. | +| `cli-metadata` | Лише збирання метаданих команд CLI. | -Записи Plugin, які відкривають сокети, бази даних, фонові воркери або довготривалі +Входи плагінів, які відкривають сокети, бази даних, фонових працівників або довгоживучі клієнти, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`. -Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють -поточний реєстр Gateway. Виявлення не є активаційним, але не є вільним від імпортів: -OpenClaw може виконати довірений вхід Plugin або модуль Plugin каналу, щоб побудувати -знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а мережеві -клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб переносьте -за шляхи повного середовища виконання. +Завантаження виявлення кешуються окремо від завантажень активації й не замінюють +поточний реєстр Gateway. Виявлення не активує, але й не є вільним від імпортів: +OpenClaw може виконати довірений вхід плагіна або модуль канального плагіна, щоб побудувати +знімок. Тримайте верхні рівні модулів легковаговими й без побічних ефектів, а +мережевих клієнтів, підпроцеси, слухачі, читання облікових даних і запуск служб +переносьте за шляхи повного виконання. Поширені методи реєстрації: @@ -566,42 +563,42 @@ OpenClaw може виконати довірений вхід Plugin або м | `registerTool` | Інструмент агента | | `registerHook` / `on(...)` | Хуки життєвого циклу | | `registerSpeechProvider` | Перетворення тексту на мовлення / STT | -| `registerRealtimeTranscriptionProvider` | Потокове STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | | `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | | `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | | `registerImageGenerationProvider` | Генерація зображень | | `registerMusicGenerationProvider` | Генерація музики | | `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер веботримання / скрейпінгу | +| `registerWebFetchProvider` | Провайдер вебзавантаження / скрейпінгу | | `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP-ендпоінт | +| `registerHttpRoute` | HTTP endpoint | | `registerCommand` / `registerCli` | Команди CLI | | `registerContextEngine` | Рушій контексту | | `registerService` | Фонова служба | Поведінка захисту хуків для типізованих хуків життєвого циклу: -- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. -- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. -- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. +- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: `{ block: false }` є no-op і не скасовує попередній блок. +- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. +- `before_install`: `{ block: false }` є no-op і не скасовує попередній блок. +- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. +- `message_sending`: `{ cancel: false }` є no-op і не скасовує попереднє скасування. -Нативний сервер застосунку Codex повертає події нативних інструментів Codex через міст -на цю поверхню хуків. Plugin можуть блокувати нативні інструменти Codex через `before_tool_call`, -спостерігати результати через `after_tool_call` та брати участь у схваленнях Codex +Нативний сервер застосунку Codex передає нативні для Codex події інструментів назад у цю +поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, +спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex `PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. Точна межа підтримки середовища виконання Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). -## Пов'язане +## Пов’язане -- [Створення Plugin](/uk/plugins/building-plugins) — створіть власний Plugin -- [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін +- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor - [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагін - [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Спільнотні Plugin](/uk/plugins/community) — переліки сторонніх розробників +- [Плагіни спільноти](/uk/plugins/community) — сторонні каталоги