From f859338078b64079d08fe315ee5e1d468779b629 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 14:35:54 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/manifest.md | 987 ++++++++++++++++++----------------- docs/uk/plugins/sdk-setup.md | 219 ++++---- 2 files changed, 605 insertions(+), 601 deletions(-) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 304a5f141..39368dca9 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,64 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно випустити схему конфігурації Plugin або налагодити помилки перевірки Plugin -summary: Вимоги до маніфесту Plugin + схеми JSON (строга перевірка конфігурації) + - Ви створюєте OpenClaw Plugin + - Вам потрібно випустити схему конфігурації Plugin або налагодити помилки валідації Plugin +summary: Вимоги до маніфесту Plugin + схеми JSON (сувора перевірка конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-05-02T08:16:30Z" + generated_at: "2026-05-02T14:31:47Z" model: gpt-5.5 provider: openai - source_hash: 1e9cb6eff8d35cbd819178be9885801e2b84ad29cd12bbfd2f630467914366e4 + source_hash: d21704678ef64d35aa778f7fe65114bab7a9a94bb74ff4f1d4d9b5788965f453 source_path: plugins/manifest.md workflow: 16 --- -Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. +Ця сторінка призначена лише для **нативного маніфесту плагіна OpenClaw**. -Про сумісні макети пакетів див. [Plugin-пакети](/uk/plugins/bundles). +Сумісні макети пакетів див. у [пакетах плагінів](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфестів: -- Codex bundle: `.codex-plugin/plugin.json` -- Claude bundle: `.claude-plugin/plugin.json` або типовий макет компонента Claude +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- Cursor bundle: `.cursor-plugin/plugin.json` +- Пакет Cursor: `.cursor-plugin/plugin.json` OpenClaw також автоматично виявляє ці макети пакетів, але вони не перевіряються за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета разом із оголошеними -коренями skill, коренями команд Claude, типовими значеннями Claude bundle `settings.json`, -типовими значеннями LSP для Claude bundle і підтримуваними наборами hook, коли макет відповідає +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені +корені skill, корені команд Claude, стандартні значення Claude-пакета з `settings.json`, +стандартні значення LSP Claude-пакета та підтримувані набори hooks, коли макет відповідає очікуванням runtime OpenClaw. -Кожен нативний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у -**корені Plugin**. OpenClaw використовує цей маніфест для перевірки конфігурації -**без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються -помилками Plugin і блокують перевірку конфігурації. +Кожен нативний плагін OpenClaw **повинен** постачати файл `openclaw.plugin.json` у +**корені плагіна**. OpenClaw використовує цей маніфест для перевірки конфігурації +**без виконання коду плагіна**. Відсутні або недійсні маніфести вважаються +помилками плагіна та блокують перевірку конфігурації. -Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). -Про нативну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +Див. повний посібник із системи плагінів: [Плагіни](/uk/tools/plugin). +Про нативну модель можливостей і поточні настанови щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження вашого -коду Plugin**. Усе нижче має бути достатньо дешевим для інспектування без запуску -runtime Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження вашого +коду плагіна**. Усе нижче має бути достатньо легким для перевірки без запуску +runtime плагіна. **Використовуйте його для:** -- ідентичності Plugin, перевірки конфігурації та підказок UI конфігурації -- метаданих auth, onboarding і налаштування (alias, auto-enable, provider env vars, auth choices) +- ідентичності плагіна, перевірки конфігурації та підказок UI конфігурації +- метаданих автентифікації, onboarding і налаштування (alias, auto-enable, env vars провайдера, варіанти автентифікації) - підказок активації для поверхонь control-plane -- скороченого володіння сімейством моделей +- скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які спільний host `openclaw qa` може інспектувати -- channel-specific метаданих конфігурації, об’єднаних у catalog і поверхні перевірки +- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- специфічних для каналу метаданих конфігурації, об’єднаних у каталог і поверхні перевірки -**Не використовуйте його для:** реєстрації runtime-поведінки, оголошення entrypoints коду -або метаданих npm install. Вони належать до вашого коду Plugin і `package.json`. +**Не використовуйте його для:** реєстрації runtime-поведінки, оголошення code entrypoints +або метаданих встановлення npm. Вони належать до коду вашого плагіна та `package.json`. ## Мінімальний приклад @@ -152,54 +152,54 @@ runtime Plugin. ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що це означає | +| Поле | Обов’язкове | Тип | Що означає | | ------------------------------------ | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | +| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | | `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, що належать цьому Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, що належать цьому Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до полегшеного модуля виявлення провайдера, відносно кореня Plugin, для обмежених маніфестом метаданих каталогу провайдера, які можна завантажити без активації повного runtime Plugin. | -| `modelSupport` | Ні | `object` | Належні маніфесту скорочені метадані сімейства моделей, що використовуються для автоматичного завантаження Plugin перед runtime. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, що належать цьому Plugin. Це контракт площини керування для майбутнього read-only переліку, onboarding, вибирачів моделей, псевдонімів і приглушення без завантаження runtime Plugin. | -| `modelPricing` | Ні | `object` | Належна провайдеру політика зовнішнього пошуку цін. Використовуйте її, щоб виключити локальні/self-hosted провайдери з віддалених каталогів цін або зіставити посилання провайдера з ідентифікаторами каталогів OpenRouter/LiteLLM без жорстко закодованих ідентифікаторів провайдерів у core. | -| `modelIdNormalization` | Ні | `object` | Належне провайдеру очищення псевдонімів/префіксів ідентифікаторів моделей, яке має виконуватися до завантаження runtime провайдера. | -| `providerEndpoints` | Ні | `object[]` | Належні маніфесту метадані endpoint host/baseUrl для маршрутів провайдера, які core має класифікувати до завантаження runtime провайдера. | -| `providerRequest` | Ні | `object` | Недорогі метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження runtime провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, що належать цьому Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або бекенд CLI, для яких належний Plugin synthetic auth hook має перевірятися під час холодного виявлення моделей до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Належні вбудованому Plugin значення-заповнювачі API key, що представляють несекретний локальний, OAuth або ambient credential стан. | -| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому Plugin і мають створювати обізнані про Plugin діагностику конфігурації та CLI до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом періоду вилучення. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding-провайдер, що спільно використовує API key і профілі автентифікації базового провайдера. | -| `channelEnvVars` | Ні | `Record` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для керованого env налаштування каналів або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для onboarding-вибирачів, визначення бажаного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Недорогі метадані планувальника активації для завантаження, спричиненого запуском, провайдером, командою, каналом, маршрутом і capability. Лише метадані; runtime Plugin усе ще володіє фактичною поведінкою. | -| `setup` | Ні | `object` | Недорогі дескриптори налаштування/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin. | -| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, що використовуються спільним host `openclaw qa` до завантаження runtime Plugin. | -| `contracts` | Ні | `object` | Статичний знімок володіння capability для зовнішніх auth hooks, мовлення, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Недорогі типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `imageGenerationProviderMetadata` | Ні | `Record` | Недорогі метадані автентифікації image-generation для ідентифікаторів провайдерів, оголошених у `contracts.imageGenerationProviders`, зокрема належні провайдеру псевдоніми автентифікації та base-url guards. | -| `videoGenerationProviderMetadata` | Ні | `Record` | Недорогі метадані автентифікації video-generation для ідентифікаторів провайдерів, оголошених у `contracts.videoGenerationProviders`, зокрема належні провайдеру псевдоніми автентифікації та base-url guards. | -| `musicGenerationProviderMetadata` | Ні | `Record` | Недорогі метадані автентифікації music-generation для ідентифікаторів провайдерів, оголошених у `contracts.musicGenerationProviders`, зокрема належні провайдеру псевдоніми автентифікації та base-url guards. | -| `toolMetadata` | Ні | `Record` | Недорогі метадані доступності для належних Plugin інструментів, оголошених у `contracts.tools`. Використовуйте їх, коли інструмент не має завантажувати runtime, якщо немає доказів конфігурації, env або автентифікації. | -| `channelConfigs` | Ні | `Record` | Належні маніфесту метадані конфігурації каналу, об’єднані з поверхнями виявлення та валідації до завантаження runtime. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ids, які нормалізуються до цього канонічного id Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Provider ids, які мають автоматично вмикати цей Plugin, коли auth, config або model refs згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний вид Plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Channel ids, що належать цьому Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Provider ids, що належать цьому Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Легкий шлях до модуля виявлення providers, відносно кореня Plugin, для metadata каталогу providers у межах manifest, які можна завантажити без активації повного runtime Plugin. | +| `modelSupport` | Ні | `object` | Скорочені metadata сімейств моделей, що належать manifest і використовуються для автозавантаження Plugin перед runtime. | +| `modelCatalog` | Ні | `object` | Декларативні metadata каталогу моделей для providers, що належать цьому Plugin. Це контракт control plane для майбутнього read-only переліку, onboarding, вибирачів моделей, aliases і suppression без завантаження runtime Plugin. | +| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку pricing, що належить provider. Використовуйте її, щоб виключати локальні/self-hosted providers з віддалених pricing catalogs або зіставляти provider refs з ids каталогів OpenRouter/LiteLLM без жорсткого кодування provider ids у core. | +| `modelIdNormalization` | Ні | `object` | Очищення aliases/prefixes model id, що належить provider і має виконуватися до завантаження runtime provider. | +| `providerEndpoints` | Ні | `object[]` | Metadata host/baseUrl endpoints, що належать manifest, для provider routes, які core має класифікувати до завантаження runtime provider. | +| `providerRequest` | Ні | `object` | Дешеві metadata сімейства provider і сумісності request, що використовуються загальною policy request до завантаження runtime provider. | +| `cliBackends` | Ні | `string[]` | CLI inference backend ids, що належать цьому Plugin. Використовується для автоматичної активації під час запуску з явних config refs. | +| `syntheticAuthRefs` | Ні | `string[]` | Provider або CLI backend refs, чий synthetic auth hook, що належить Plugin, має перевірятися під час холодного виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать вбудованому Plugin і представляють несекретний локальний, OAuth або ambient credential state. | +| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому Plugin і мають створювати config та CLI diagnostics з урахуванням Plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі metadata сумісності env для пошуку auth/status provider. Для нових plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw досі читає це поле протягом періоду deprecation. | +| `providerAuthAliases` | Ні | `Record` | Provider ids, які мають повторно використовувати інший provider id для пошуку auth, наприклад coding provider, що ділить API key і auth profiles базового provider. | +| `channelEnvVars` | Ні | `Record` | Дешеві channel env metadata, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для channel setup на основі env або auth surfaces, які мають бачити загальні startup/config helpers. | +| `providerAuthChoices` | Ні | `object[]` | Дешеві metadata auth choices для onboarding pickers, preferred-provider resolution і простого підключення CLI flags. | +| `activation` | Ні | `object` | Дешеві metadata планувальника активації для завантаження, що запускається startup, provider, command, channel, route та capability. Лише metadata; runtime Plugin все ще володіє фактичною поведінкою. | +| `setup` | Ні | `object` | Дешеві descriptors setup/onboarding, які surfaces discovery і setup можуть перевіряти без завантаження runtime Plugin. | +| `qaRunners` | Ні | `object[]` | Дешеві descriptors QA runner, що використовуються спільним host `openclaw qa` до завантаження runtime Plugin. | +| `contracts` | Ні | `object` | Статичний snapshot ownership capabilities для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і tool ownership. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві defaults media-understanding для provider ids, оголошених у `contracts.mediaUnderstandingProviders`. | +| `imageGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata image-generation для provider ids, оголошених у `contracts.imageGenerationProviders`, включно з auth aliases і base-url guards, що належать provider. | +| `videoGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata video-generation для provider ids, оголошених у `contracts.videoGenerationProviders`, включно з auth aliases і base-url guards, що належать provider. | +| `musicGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata music-generation для provider ids, оголошених у `contracts.musicGenerationProviders`, включно з auth aliases і base-url guards, що належать provider. | +| `toolMetadata` | Ні | `Record` | Дешеві metadata доступності для tools, що належать Plugin і оголошені в `contracts.tools`. Використовуйте це, коли tool не має завантажувати runtime, якщо немає доказів config, env або auth. | +| `channelConfigs` | Ні | `Record` | Channel config metadata, що належать manifest і зливаються в surfaces discovery та validation до завантаження runtime. | | `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | | `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що відображається на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | +| `description` | Ні | `string` | Короткий підсумок, що показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | UI-мітки, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник метаданих провайдера генерації Поля метаданих провайдера генерації описують статичні сигнали автентифікації для провайдерів, оголошених у відповідному списку `contracts.*GenerationProviders`. -OpenClaw читає ці поля до завантаження середовища виконання провайдера, щоб інструменти ядра могли -визначити, чи доступний провайдер генерації, без імпортування кожного -Plugin провайдера. +OpenClaw читає ці поля до завантаження середовища виконання провайдера, щоб основні інструменти могли +вирішити, чи доступний провайдер генерації, без імпорту кожного +провайдерського Plugin. Використовуйте ці поля лише для дешевих декларативних фактів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації @@ -247,53 +247,53 @@ Plugin провайдера. Кожен запис метаданих підтримує: -| Поле | Обов’язкове | Тип | Що це означає | -| --------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `aliases` | Ні | `string[]` | Додаткові ідентифікатори провайдерів, які мають вважатися статичними псевдонімами автентифікації для провайдера генерації. | -| `authProviders` | Ні | `string[]` | Ідентифікатори провайдерів, чиї налаштовані профілі автентифікації мають вважатися автентифікацією для цього провайдера генерації. | -| `configSignals` | Ні | `object[]` | Дешеві сигнали доступності лише з конфігурації для локальних або самостійно розміщених провайдерів, які можна налаштувати без профілів автентифікації чи змінних середовища. | -| `authSignals` | Ні | `object[]` | Явні сигнали автентифікації. Якщо вони присутні, вони замінюють стандартний набір сигналів з ідентифікатора провайдера, `aliases` і `authProviders`. | +| Поле | Обов’язкове | Тип | Що це означає | +| --------------- | ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `aliases` | Ні | `string[]` | Додаткові ідентифікатори провайдерів, які мають враховуватися як статичні псевдоніми автентифікації для провайдера генерації. | +| `authProviders` | Ні | `string[]` | Ідентифікатори провайдерів, чиї налаштовані профілі автентифікації мають враховуватися як автентифікація для цього провайдера генерації. | +| `configSignals` | Ні | `object[]` | Дешеві сигнали доступності лише за конфігурацією для локальних або самостійно розгорнутих провайдерів, які можна налаштувати без профілів автентифікації чи змінних середовища. | +| `authSignals` | Ні | `object[]` | Явні сигнали автентифікації. Якщо вони присутні, то замінюють стандартний набір сигналів з ідентифікатора провайдера, `aliases` і `authProviders`. | Кожен запис `configSignals` підтримує: -| Поле | Обов’язкове | Тип | Що це означає | -| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `rootPath` | Так | `string` | Dot path до об’єкта конфігурації, що належить Plugin, який потрібно перевірити, наприклад `plugins.entries.example.config`. | -| `overlayPath` | Ні | `string` | Dot path усередині кореневої конфігурації, чий об’єкт має накладатися на кореневий об’єкт перед оцінюванням сигналу. Використовуйте це для конфігурації, специфічної для можливості, як-от `image`, `video` або `music`. | -| `required` | Ні | `string[]` | Dot paths усередині ефективної конфігурації, які мають мати налаштовані значення. Рядки мають бути непорожніми; об’єкти й масиви не мають бути порожніми. | -| `requiredAny` | Ні | `string[]` | Dot paths усередині ефективної конфігурації, де принаймні один має мати налаштоване значення. | -| `mode` | Ні | `object` | Необов’язковий запобіжник рядкового режиму всередині ефективної конфігурації. Використовуйте його, коли доступність лише з конфігурації застосовується тільки до одного режиму. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `rootPath` | Так | `string` | Шлях через крапки до об’єкта конфігурації, яким володіє Plugin, наприклад `plugins.entries.example.config`. | +| `overlayPath` | Ні | `string` | Шлях через крапки всередині кореневої конфігурації, об’єкт якого має накладатися на кореневий об’єкт перед оцінюванням сигналу. Використовуйте це для конфігурації, специфічної для можливості, як-от `image`, `video` або `music`. | +| `required` | Ні | `string[]` | Шляхи через крапки всередині ефективної конфігурації, які повинні мати налаштовані значення. Рядки мають бути непорожніми; об’єкти й масиви не мають бути порожніми. | +| `requiredAny` | Ні | `string[]` | Шляхи через крапки всередині ефективної конфігурації, серед яких принаймні один повинен мати налаштоване значення. | +| `mode` | Ні | `object` | Необов’язковий захист за рядковим режимом усередині ефективної конфігурації. Використовуйте це, коли доступність лише за конфігурацією застосовується тільки до одного режиму. | -Кожен запобіжник `mode` підтримує: +Кожен захист `mode` підтримує: -| Поле | Обов’язкове | Тип | Що це означає | -| ------------ | ----------- | ---------- | -------------------------------------------------------------------------------------- | -| `path` | Ні | `string` | Dot path усередині ефективної конфігурації. За замовчуванням `mode`. | -| `default` | Ні | `string` | Значення режиму, яке слід використовувати, коли конфігурація пропускає шлях. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------ | ----------- | ---------- | ---------------------------------------------------------------------------------- | +| `path` | Ні | `string` | Шлях через крапки всередині ефективної конфігурації. За замовчуванням `mode`. | +| `default` | Ні | `string` | Значення режиму, яке слід використовувати, коли конфігурація пропускає шлях. | | `allowed` | Ні | `string[]` | Якщо присутнє, сигнал проходить лише тоді, коли ефективний режим є одним із цих значень. | -| `disallowed` | Ні | `string[]` | Якщо присутнє, сигнал не проходить, коли ефективний режим є одним із цих значень. | +| `disallowed` | Ні | `string[]` | Якщо присутнє, сигнал не проходить, коли ефективний режим є одним із цих значень. | Кожен запис `authSignals` підтримує: -| Поле | Обов’язкове | Тип | Що це означає | -| ---------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера для перевірки в налаштованих профілях автентифікації. | -| `providerBaseUrl` | Ні | `object` | Необов’язковий запобіжник, через який сигнал враховується лише тоді, коли вказаний налаштований провайдер використовує дозволену базову URL-адресу. Використовуйте це, коли псевдонім автентифікації чинний лише для певних API. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера для перевірки в налаштованих профілях автентифікації. | +| `providerBaseUrl` | Ні | `object` | Необов’язковий захист, через який сигнал враховується лише тоді, коли вказаний налаштований провайдер використовує дозволений базовий URL. Використовуйте це, коли псевдонім автентифікації чинний лише для певних API. | -Кожен запобіжник `providerBaseUrl` підтримує: +Кожен захист `providerBaseUrl` підтримує: -| Поле | Обов’язкове | Тип | Що це означає | -| ---------------- | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор конфігурації провайдера, чий `baseUrl` потрібно перевірити. | -| `defaultBaseUrl` | Ні | `string` | Базова URL-адреса, яку слід припускати, коли конфігурація провайдера пропускає `baseUrl`. | -| `allowedBaseUrls` | Так | `string[]` | Дозволені базові URL-адреси для цього сигналу автентифікації. Сигнал ігнорується, коли налаштована або стандартна базова URL-адреса не збігається з одним із цих нормалізованих значень. | +| Поле | Обов’язкове | Тип | Що це означає | +| ----------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор конфігурації провайдера, чий `baseUrl` потрібно перевіряти. | +| `defaultBaseUrl` | Ні | `string` | Базовий URL, який слід припускати, коли конфігурація провайдера пропускає `baseUrl`. | +| `allowedBaseUrls` | Так | `string[]` | Дозволені базові URL для цього сигналу автентифікації. Сигнал ігнорується, коли налаштований або стандартний базовий URL не збігається з одним із цих нормалізованих значень. | ## Довідник метаданих інструментів `toolMetadata` використовує ті самі форми `configSignals` і `authSignals`, що й метадані провайдера генерації, з ключами за назвою інструмента. `contracts.tools` оголошує -власника. `toolMetadata` оголошує дешеві докази доступності, щоб OpenClaw міг -уникати імпортування середовища виконання Plugin лише для того, щоб фабрика інструмента повернула `null`. +володіння. `toolMetadata` оголошує дешеві докази доступності, щоб OpenClaw міг +уникати імпорту середовища виконання Plugin лише для того, щоб фабрика його інструмента повернула `null`. ```json { @@ -323,41 +323,41 @@ Plugin провайдера. ``` Якщо інструмент не має `toolMetadata`, OpenClaw зберігає наявну поведінку й -завантажує Plugin-власник, коли контракт інструмента відповідає політиці. Для інструментів +завантажує власницький Plugin, коли контракт інструмента відповідає політиці. Для інструментів гарячого шляху, фабрика яких залежить від автентифікації/конфігурації, авторам Plugin слід оголошувати `toolMetadata` замість того, щоб змушувати ядро імпортувати середовище виконання для запиту. ## Довідник providerAuthChoices -Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. +Кожен запис `providerAuthChoices` описує один вибір онбордингу або автентифікації. OpenClaw читає це до завантаження середовища виконання провайдера. -Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти налаштування, -отримані з дескриптора, і метадані каталогу встановлення без завантаження середовища виконання провайдера. +Списки налаштування провайдера використовують ці вибори з маніфесту, вибори налаштування, +похідні від дескриптора, і метадані каталогу встановлення без завантаження середовища виконання провайдера. -| Поле | Обов’язкове | Тип | Що це означає | -| --------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації для передавання. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її пропущено, OpenClaw повертається до `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для вибору. | -| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних вибирачах, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховати варіант із вибирачів асистента, водночас дозволяючи ручний вибір у CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта заміни. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типовим значенням є `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей вибір. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації для передавання. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовується потоками онбордингу й CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її пропущено, OpenClaw повертається до `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для вибірника. | +| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних вибірниках, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує вибір із вибірників асистента, водночас дозволяючи ручний вибір у CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори вибору, які мають перенаправляти користувачів до цього вибору-заміни. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних виборів. | +| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей вибір. Якщо пропущено, стандартно використовується `["text-inference"]`. | ## Довідник commandAliases -Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. +Use `commandAliases`, коли плагін володіє назвою runtime-команди, яку користувачі можуть +помилково додати до `plugins.allow` або спробувати запустити як кореневу CLI-команду. OpenClaw +використовує ці метадані для діагностики без імпорту runtime-коду плагіна. ```json { @@ -371,43 +371,43 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому плагіну. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як слеш-команду чату, а не як кореневу CLI-команду. | +| `cliCommand` | Ні | `string` | Пов’язана коренева CLI-команда, яку слід запропонувати для CLI-операцій, якщо така існує. | -## довідник activation +## довідка з activation -Використовуйте `activation`, коли Plugin може недорого оголосити, які події площини керування +Use `activation`, коли плагін може дешево оголосити, які події control plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку середовища виконання, не замінює `register(...)` і не гарантує, що -код Plugin уже виконався. Планувальник активації використовує ці поля, щоб -звузити набір кандидатів Plugin перед поверненням до наявних метаданих володіння маніфесту, -таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє +runtime-поведінку, не замінює `register(...)` і не обіцяє, що +код плагіна вже виконано. Планувальник активації використовує ці поля, щоб +звузити перелік кандидатних плагінів перед поверненням до наявних метаданих +володіння маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +`providers`, `channels`, `commandAliases`, setup-дескриптори або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, які не можна представити цими полями володіння. -Використовуйте верхньорівневі `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, +Використовуйте верхньорівневе `cliBackends` для CLI runtime-псевдонімів, як-от `claude-cli`, `codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для вбудованих ідентифікаторів agent harness, які ще не мають поля володіння. -Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не -замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації поза запуском зазвичай лише впливає на продуктивність; вона -не повинна змінювати коректність, доки ще існують резервні варіанти володіння маніфесту. +Цей блок є лише метаданими. Він не реєструє runtime-поведінку й не замінює +`register(...)`, `setupEntry` або інші runtime/plugin entrypoints. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагінів, тому +відсутні метадані активації не під час запуску зазвичай впливають лише на продуктивність; це +не має змінювати коректність, поки існують fallback-и володіння маніфесту. -Кожен Plugin має встановлювати `activation.onStartup` навмисно. Встановлюйте його в `true` -лише тоді, коли Plugin повинен виконуватися під час запуску Gateway. Встановлюйте його в `false`, коли -Plugin неактивний під час запуску й має завантажуватися лише через вужчі тригери. -Пропуск `onStartup` більше не запускає Plugin неявно під час старту; використовуйте явні -метадані активації для запуску, каналу, конфігурації, agent harness, пам’яті або +Кожен плагін має задавати `activation.onStartup` навмисно. Установлюйте його в `true` +лише тоді, коли плагін має виконуватися під час запуску Gateway. Установлюйте його в `false`, коли +плагін інертний під час запуску й має завантажуватися лише за вужчими тригерами. +Пропуск `onStartup` більше не завантажує плагін під час запуску неявно; використовуйте явні +метадані активації для запуску, каналу, конфігурації, agent-harness, пам’яті або інших вужчих тригерів активації. ```json @@ -424,46 +424,44 @@ Plugin неактивний під час запуску й має завант } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------------ | -------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час запуску; `false` залишає його лінивим під час запуску, якщо інший відповідний тригер не потребує завантаження. | -| `onProviders` | Ні | `string[]` | Ідентифікатори providers, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте верхньорівневі `cliBackends` для псевдонімів CLI backend. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів запуску/завантаження, коли шлях наявний і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовує планування активації площини керування. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен плагін має задавати це поле. `true` імпортує плагін під час запуску; `false` зберігає його лінивим на запуску, якщо інший відповідний тригер не вимагає завантаження. | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей плагін до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Runtime-ідентифікатори вбудованих agent harness, які мають включати цей плагін до планів активації/завантаження. Використовуйте верхньорівневе `cliBackends` для псевдонімів CLI backend. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей плагін до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей плагін до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей плагін до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей плагін до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовуються плануванням активації control plane. За можливості надавайте перевагу вужчим полям. | Поточні live-споживачі: -- планування запуску Gateway використовує `activation.onStartup` для явного імпорту - під час запуску -- планування CLI, спричинене командами, повертається до застарілих +- Планування запуску Gateway використовує `activation.onStartup` для явного імпорту під час запуску +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` - планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harness і верхньорівневі `cliBackends[]` для псевдонімів середовища виконання CLI -- планування setup/channel, спричинене каналом, повертається до застарілого володіння `channels[]`, - коли явні метадані активації каналу відсутні -- планування Plugin під час запуску використовує `activation.onConfigPaths` для неканальних кореневих - поверхонь конфігурації, таких як блок `browser` вбудованого browser Plugin -- планування setup/runtime, спричинене provider, повертається до застарілого володіння - `providers[]` і верхньорівневих `cliBackends[]`, коли явні метадані активації provider - відсутні + вбудованих harness і верхньорівневе `cliBackends[]` для CLI runtime-псевдонімів +- планування setup/channel, що запускається каналом, повертається до застарілого володіння `channels[]`, + коли явних метаданих активації каналу немає +- планування плагінів під час запуску використовує `activation.onConfigPaths` для неканальних кореневих + поверхонь конфігурації, як-от блок `browser` вбудованого browser-плагіна +- планування setup/runtime, що запускається провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явних метаданих активації провайдера немає -Діагностика планувальника може відрізняти явні підказки активації від резервного варіанта +Діагностика планувальника може розрізняти явні підказки активації та fallback володіння маніфесту. Наприклад, `activation-command-hint` означає, що `activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста й тестів; автори Plugin мають і надалі оголошувати метадані, +діагностики хоста й тестів; автори плагінів мають і надалі оголошувати метадані, які найкраще описують володіння. -## довідник qaRunners +## довідка з qaRunners -Використовуйте `qaRunners`, коли Plugin додає один або кілька транспортних runner під -спільний корінь `openclaw qa`. Тримайте ці метадані дешевими й статичними; середовище виконання Plugin -і надалі володіє фактичною реєстрацією CLI через легковагову -поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Use `qaRunners`, коли плагін додає один або кілька transport runner під +спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими й статичними; runtime плагіна +й надалі володіє фактичною реєстрацією CLI через легку поверхню +`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -476,15 +474,15 @@ Plugin неактивний під час запуску й має завант } ``` -| Поле | Обов’язкове | Тип | Що це означає | -| ------------- | -------- | -------- | -------------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | -## довідник setup +## довідка з setup -Використовуйте `setup`, коли поверхням setup і onboarding потрібні дешеві метадані, якими володіє Plugin, -до завантаження середовища виконання. +Use `setup`, коли поверхням setup і onboarding потрібні дешеві метадані, якими володіє плагін, +до завантаження runtime. ```json { @@ -512,79 +510,79 @@ Plugin неактивний під час запуску й має завант } ``` -Верхньорівневий `cliBackends` залишається чинним і продовжує описувати backend CLI inference. -`setup.cliBackends` є специфічною для setup поверхнею дескрипторів для -потоків площини керування/setup, які мають залишатися лише метаданими. +Верхньорівневе `cliBackends` залишається чинним і далі описує CLI inference +backends. `setup.cliBackends` є setup-специфічною поверхнею дескрипторів для +потоків control-plane/setup, які мають залишатися лише метаданими. -Коли `setup.providers` і `setup.cliBackends` наявні, вони є бажаною +Коли присутні `setup.providers` і `setup.cliBackends`, вони є бажаною descriptor-first поверхнею пошуку для виявлення setup. Якщо дескриптор лише -звужує кандидатний Plugin, а setup усе ще потребує багатших runtime hooks під час setup, -встановіть `requiresRuntime: true` і залиште `setup-api` як +звужує кандидатний плагін, а setup все ще потребує багатших runtime hooks під час setup, +установіть `requiresRuntime: true` і залиште `setup-api` на місці як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації provider і -env-var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності -протягом періоду виведення з ужитку, але невбудовані plugins, які досі його використовують, -отримують діагностику маніфесту. Нові plugins мають розміщувати env-метадані setup/status +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків авторизації провайдера та +env-var. `providerAuthEnvVars` залишається підтримуваним через compatibility +adapter протягом періоду вилучення, але невбудовані плагіни, які досі його використовують, +отримують діагностику маніфесту. Нові плагіни мають розміщувати env-метадані setup/status у `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, -коли запис setup недоступний або коли `setup.requiresRuntime: false` -оголошує, що середовище виконання setup не потрібне. Явні записи `providerAuthChoices` залишаються -бажаними для власних міток, прапорців CLI, області onboarding і метаданих assistant. +OpenClaw також може виводити прості setup choices із `setup.providers[].authMethods`, +коли немає setup entry або коли `setup.requiresRuntime: false` +оголошує, що setup runtime не потрібен. Явні записи `providerAuthChoices` залишаються +бажаними для власних міток, CLI-прапорців, onboarding scope і метаданих assistant. -Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на основі дескрипторів -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin, що працює лише на дескрипторах, усе ж постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й продовжує ігнорувати його. Пропущене -`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як descriptor-only контракт +і не виконуватиме `setup-api` або `openclaw.setupEntry` для setup lookup. Якщо +descriptor-only плагін усе одно постачає один із цих setup runtime entries, +OpenClaw повідомляє additive diagnostic і продовжує його ігнорувати. Пропущене +`requiresRuntime` зберігає застарілу fallback-поведінку, щоб наявні плагіни, які додали дескриптори без прапорця, не зламалися. -Оскільки пошук setup може виконувати код `setup-api`, яким володіє Plugin, нормалізовані -значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -виявлених plugins. Неоднозначне володіння завершується відмовою, замість вибору +Оскільки setup lookup може виконувати код `setup-api`, яким володіє плагін, нормалізовані +значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними в усіх +виявлених плагінах. Неоднозначне володіння fail closed замість вибору переможця за порядком виявлення. -Коли середовище виконання setup виконується, діагностика реєстру setup повідомляє про розбіжність дескрипторів, -якщо `setup-api` реєструє provider або CLI backend, які дескриптори маніфесту -не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. -Ця діагностика є додатковою й не відхиляє застарілі plugins. +Коли setup runtime виконується, діагностика setup registry повідомляє про descriptor +drift, якщо `setup-api` реєструє провайдера або CLI backend, які дескриптори маніфесту +не оголошують, або якщо дескриптор не має відповідної runtime +реєстрації. Ці діагностики є additive й не відхиляють застарілі плагіни. -### довідник setup.providers +### довідка з setup.providers -| Поле | Обов’язкове | Тип | Що це означає | -| -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор provider, відкритий під час setup або onboarding. Тримайте нормалізовані ідентифікатори глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження середовища виконання Plugin. | -| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів автентифікації для providers, які можуть автентифікуватися через несекретні маркери. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------- | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час setup або onboarding. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime плагіна. | +| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки auth evidence для провайдерів, які можуть автентифікуватися через non-secret markers. | -`authEvidence` призначено для локальних маркерів облікових даних, якими володіє провайдер і які можна +`authEvidence` призначений для локальних маркерів облікових даних, що належать провайдеру, які можна перевірити без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або менеджера секретів, без shell-команд і без проб API провайдера. -Підтримувані записи evidence: +Підтримувані записи доказів: | Поле | Обов’язкове | Тип | Що це означає | | ------------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `type` | Так | `string` | Наразі `local-file-with-env`. | -| `fileEnvVar` | Ні | `string` | Змінна середовища, що містить явний шлях до файлу облікових даних. | +| `fileEnvVar` | Ні | `string` | Змінна середовища, що містить явний шлях до файла облікових даних. | | `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | -| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна зі вказаних змінних середовища має бути непорожньою, перш ніж evidence стане чинним. | -| `requiresAllEnv` | Ні | `string[]` | Кожна зі вказаних змінних середовища має бути непорожньою, перш ніж evidence стане чинним. | -| `credentialMarker` | Так | `string` | Несекретний маркер, який повертається, коли evidence наявний. | -| `source` | Ні | `string` | Видима користувачу мітка джерела для виводу auth/status. | +| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна зі вказаних змінних середовища має бути непорожньою, перш ніж доказ стане дійсним. | +| `requiresAllEnv` | Ні | `string[]` | Кожна зі вказаних змінних середовища має бути непорожньою, перш ніж доказ стане дійсним. | +| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ присутній. | +| `source` | Ні | `string` | Видима користувачу мітка джерела для виводу автентифікації/статусу. | ### Поля setup | Поле | Обов’язкове | Тип | Що це означає | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup і onboarding. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend, що використовуються під час setup для пошуку за принципом descriptor-first. Тримайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє setup-поверхня цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку дескриптора. | +| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, доступні під час setup і onboarding. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів часу налаштування, що використовуються для setup-пошуку спершу за дескриптором. Тримайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup усе ще потребує виконання `setup-api` після пошуку дескриптора. | ## Довідник uiHints @@ -609,15 +607,15 @@ OpenClaw повідомляє додаткову діагностику й пр | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Видима користувачу мітка поля. | | `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теги. | +| `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник contracts Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -читати без імпорту runtime plugin. +прочитати без імпорту runtime plugin. ```json { @@ -639,51 +637,51 @@ OpenClaw повідомляє додаткову діагностику й пр } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: | Поле | Тип | Що це означає | | -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори extension factory app-server Codex, наразі `codex-app-server`. | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | Runtime-ідентифікатори, для яких bundled plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, external auth profile hook яких належить цьому plugin. | -| `speechProviders` | `string[]` | Ідентифікатори мовленнєвих провайдерів, якими володіє цей plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-транскрипції, якими володіє цей plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори realtime-voice провайдерів, якими володіє цей plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web-search, якими володіє цей plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви агентських інструментів, якими володіє цей plugin. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий hook зовнішнього профілю автентифікації належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, що належать цьому plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, що належать цьому plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори голосових провайдерів реального часу, що належать цьому plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding пам’яті, що належать цьому plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, що належать цьому plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, що належать цьому plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, що належать цьому plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, що належать цьому plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web-search, що належать цьому plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, що належать цьому plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, що належать цьому plugin. | `contracts.embeddedExtensionFactories` збережено для bundled фабрик розширень Codex -лише для app-server. Bundled перетворення tool-result мають +лише для app-server. Bundled перетворення результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть -реєструвати middleware tool-result, оскільки цей seam може переписувати високодовірений вивід інструменту -до того, як модель його побачить. +реєструвати middleware результатів інструментів, бо цей seam може переписувати високодовірений +вивід інструмента до того, як його побачить модель. Runtime-реєстрації `api.registerTool(...)` мають відповідати `contracts.tools`. -Виявлення інструментів використовує цей список, щоб завантажувати лише runtime тих plugins, які можуть володіти +Виявлення інструментів використовує цей список, щоб завантажувати лише ті runtimes plugin, які можуть володіти запитаними інструментами. Provider plugins, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugins без такого оголошення все ще проходять -через застарілий compatibility fallback, але цей fallback повільніший і -буде вилучений після migration window. +`contracts.externalAuthProviders`. Plugins без такого оголошення все ще працюють +через застарілий fallback сумісності, але цей fallback повільніший і +буде вилучений після вікна міграції. Bundled провайдери memory embedding мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного adapter id, який вони надають, включно з -вбудованими адаптерами, такими як `local`. Standalone CLI-шляхи використовують цей контракт маніфесту, -щоб завантажити лише plugin-власника до того, як повний runtime Gateway +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з +вбудованими адаптерами, такими як `local`. Автономні CLI-шляхи використовують цей manifest +contract, щоб завантажити лише plugin-власника до того, як повний Gateway runtime зареєструє провайдерів. ## Довідник mediaUnderstandingProviderMetadata -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має -моделі за замовчуванням, пріоритет fallback auto-auth або нативну підтримку документів, які +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +моделі за замовчуванням, пріоритет auto-auth fallback або нативну підтримку документів, які generic core helpers потребують до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. @@ -713,38 +711,38 @@ generic core helpers потребують до завантаження runtime. | Поле | Тип | Що це означає | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | | `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Defaults відповідності capability-to-model, що використовуються, коли конфігурація не задає модель. | +| `defaultModels` | `Record` | Значення за замовчуванням зіставлення можливості з моделлю, що використовуються, коли конфігурація не вказує модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні document inputs, підтримувані провайдером. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. | ## Довідник channelConfigs Використовуйте `channelConfigs`, коли channel plugin потребує дешевих метаданих конфігурації до -завантаження runtime. Read-only виявлення setup/status каналу може використовувати ці метадані +завантаження runtime. Виявлення setup/status каналів лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або -коли `setup.requiresRuntime: false` оголошує, що setup runtime непотрібний. +коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. -`channelConfigs` — це метадані маніфесту plugin, а не новий top-level розділ користувацької конфігурації. -Користувачі все ще налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб вирішити, який plugin володіє цим налаштованим +`channelConfigs` — це метадані manifest plugin, а не новий top-level розділ користувацької конфігурації. +Користувачі й надалі налаштовують екземпляри каналів у `channels.`. +OpenClaw читає метадані manifest, щоб вирішити, який plugin володіє цим налаштованим каналом до виконання runtime-коду plugin. -Для channel plugin, `configSchema` і `channelConfigs` описують різні +Для channel plugin `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` Non-bundled plugins, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw все ще може завантажити plugin, але +записи `channelConfigs`. Без них OpenClaw усе ще може завантажити plugin, але cold-path schema конфігурації, setup і поверхні Control UI не можуть знати -форму параметрів, якими володіє канал, доки не виконається runtime plugin. +форму опцій, що належать каналу, доки runtime plugin не виконається. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні defaults `auto` для перевірок конфігурації команд, +`nativeSkillsAutoEnabled` можуть оголошувати статичні значення за замовчуванням `auto` для перевірок конфігурації команд, які виконуються до завантаження runtime каналу. Bundled канали також можуть публікувати -ті самі defaults через `package.json#openclaw.channel.commands` разом -з іншими метаданими каталогу каналів, якими володіє пакет. +такі самі значення за замовчуванням через `package.json#openclaw.channel.commands` поруч +з іншими метаданими каталогу каналів, що належать їхньому package. ```json { @@ -777,20 +775,20 @@ cold-path schema конфігурації, setup і поверхні Control UI Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові UI-мітки/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору й інспектування, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | -| `commands` | `object` | Статична нативна команда та автоматичні значення за замовчуванням для нативної навички для перевірок конфігурації до runtime. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові UI-мітки/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що додається до поверхонь вибору та перегляду, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | +| `commands` | `object` | Статична нативна команда та нативні автоматичні типові значення Skills для перевірок конфігурації до runtime. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugin-ів, які цей канал має випереджати на поверхнях вибору. | ### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Поширені випадки: перейменований ідентифікатор Plugin, -окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який +Використовуйте `preferOver`, коли ваш Plugin є пріоритетним власником для ідентифікатора каналу, який +також може надавати інший Plugin. Типові випадки: перейменований ідентифікатор Plugin, +окремий Plugin, що замінює bundled Plugin, або підтримуваний форк, який зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json @@ -812,21 +810,21 @@ cold-path schema конфігурації, setup і поверхні Control UI } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор каналу, і -ідентифікатор бажаного Plugin. Якщо нижчопріоритетний Plugin був вибраний лише тому, -що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній -конфігурації runtime, щоб каналом і його інструментами володів один Plugin. Явний -вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw +Коли `channels.chat` налаштовано, OpenClaw враховує і ідентифікатор каналу, і +ідентифікатор пріоритетного Plugin. Якщо нижчопріоритетний Plugin було вибрано лише тому, що +він bundled або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній +runtime-конфігурації, щоб один Plugin володів каналом і його інструментами. Явний +вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin-и, OpenClaw зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість -мовчазної зміни запитаного набору Plugin. +тихої зміни запитаного набору Plugin-ів. -Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету, і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` ідентифікаторами Plugin-ів, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі користувацької конфігурації. ## Довідник modelSupport -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш провайдерський Plugin з -коротких ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider Plugin з +коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime Plugin. ```json @@ -838,27 +836,28 @@ runtime Plugin. } ``` -OpenClaw застосовує такий пріоритет: +OpenClaw застосовує такий порядок пріоритету: -- явні посилання `provider/model` використовують належні метадані маніфесту `providers` +- явні посилання `provider/model` використовують метадані маніфесту `providers` власника - `modelPatterns` мають перевагу над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований +- якщо збігаються один non-bundled Plugin і один bundled Plugin, перемагає non-bundled Plugin -- решта неоднозначності ігнорується, доки користувач або конфігурація не вкаже провайдера +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже provider Поля: -| Поле | Тип | Що це означає | -| --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` з короткими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` із короткими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела регулярних виразів, що зіставляються з короткими ідентифікаторами моделей після вилучення суфікса профілю. | ## Довідник modelCatalog -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження runtime Plugin. Це джерело, яким володіє маніфест, для фіксованих рядків -каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення. Оновлення runtime -і надалі належить коду runtime провайдера, але маніфест повідомляє ядру, коли потрібен runtime. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей provider до +завантаження runtime Plugin. Це джерело, яким володіє маніфест, для фіксованих рядків каталогу, +псевдонімів provider, правил пригнічення та режиму виявлення. Runtime-оновлення +й надалі належить коду runtime provider, але маніфест повідомляє core, коли runtime +є обов’язковим. ```json { @@ -909,71 +908,71 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що це означає | -| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдера, якими володіє цей Plugin. Ключі також мають бути в `providers` верхнього рівня. | -| `aliases` | `Record` | Псевдоніми провайдера, які мають розв’язуватися в належного провайдера для планування каталогу або приглушень. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або чи потрібен runtime. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів provider, якими володіє цей Plugin. Ключі також мають бути в `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми provider, які мають розв’язуватися до provider, яким володіють, для планування каталогу або пригнічень. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin пригнічує з причини, специфічної для provider. | +| `discovery` | `Record` | Чи можна прочитати каталог provider з метаданих маніфесту, оновити в кеш або чи він потребує runtime. | -`aliases` бере участь у пошуку власника провайдера для планування каталогу моделей. -Цілі псевдонімів мають бути провайдерами верхнього рівня, якими володіє той самий Plugin. Коли -список, відфільтрований за провайдером, використовує псевдонім, OpenClaw може прочитати належний маніфест і -застосувати перевизначення API/базової URL-адреси псевдоніма без завантаження runtime провайдера. -Псевдоніми не розгортають нефільтровані переліки каталогу; широкі списки виводять лише -рядки належного канонічного провайдера. +`aliases` бере участь у пошуку власника provider для планування каталогу моделей. +Цілі псевдонімів мають бути provider верхнього рівня, якими володіє той самий Plugin. Коли +список, відфільтрований за provider, використовує псевдонім, OpenClaw може прочитати маніфест власника та +застосувати перевизначення API/base URL псевдоніма без завантаження runtime provider. +Псевдоніми не розширюють невідфільтровані списки каталогу; широкі списки виводять лише рядки +канонічного provider власника. -`suppressions` замінює старий хук runtime провайдера `suppressBuiltInModel`. -Записи приглушення враховуються лише тоді, коли провайдер належить Plugin або -оголошений як ключ `modelCatalog.aliases`, що спрямовує на належного провайдера. Хуки приглушення -runtime більше не викликаються під час розв’язання моделі. +`suppressions` замінює старий runtime-хук provider `suppressBuiltInModel`. +Записи пригнічення враховуються лише тоді, коли provider належить Plugin або +оголошений як ключ `modelCatalog.aliases`, що вказує на provider, яким володіють. Runtime- +хуки пригнічення більше не викликаються під час розв’язання моделей. -Поля провайдера: +Поля provider: -| Поле | Тип | Що це означає | -| --------- | ------------------------ | ----------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язкова базова URL-адреса за замовчуванням для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий API-адаптер за замовчуванням для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що це означає | +| --------- | ------------------------ | ------------------------------------------------------------------------------ | +| `baseUrl` | `string` | Необов’язкова типова base URL для моделей у цьому каталозі provider. | +| `api` | `ModelApi` | Необов’язковий типовий API-адаптер для моделей у цьому каталозі provider. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу provider. | +| `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` | Необов’язкове ефективне обмеження контексту runtime, коли воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | +| Поле | Тип | Що це означає | +| --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `id` | `string` | Локальний для provider ідентифікатор моделі, без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Нативне контекстне вікно provider. | +| `contextTokens` | `number` | Необов’язкове ефективне runtime-обмеження контексту, якщо воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість output-токенів, якщо відома. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язкове `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок узагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від доступного. | -| `replaces` | `string[]` | Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-замінника для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Пригнічуйте лише тоді, коли рядок узагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від available. | +| `replaces` | `string[]` | Старі локальні для provider ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для provider ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | -Поля приглушення: +Поля пригнічення: -| Поле | Тип | Що це означає | -| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно приглушити. Має належати цьому Plugin або бути оголошеним як належний псевдонім. | -| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно приглушити. | -| `reason` | `string` | Необов’язкове повідомлення, що показується, коли приглушений рядок запитано напряму. | -| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базової URL-адреси провайдера, потрібних перед застосуванням приглушення. | -| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації провайдера, потрібних перед застосуванням приглушення. | +| Поле | Тип | Що це означає | +| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | +| `provider` | `string` | Ідентифікатор provider для upstream-рядка, який потрібно пригнітити. Має належати цьому Plugin або бути оголошеним як власний псевдонім. | +| `model` | `string` | Локальний для provider ідентифікатор моделі, яку потрібно пригнітити. | +| `reason` | `string` | Необов’язкове повідомлення, що показується, коли пригнічений рядок запитується напряму. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів base URL provider, потрібних перед застосуванням пригнічення. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації provider, потрібних перед застосуванням пригнічення. | -Не розміщуйте дані, потрібні лише під час виконання, у `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списків і вибору з фільтрацією за провайдером могли пропускати виявлення через реєстр/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення/кеш зможе додати більше рядків пізніше; рядки refreshable самі собою не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб дізнатися список. +Не розміщуйте дані, призначені лише для середовища виконання, у `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку з фільтрацією за провайдером і вибору могли пропускати виявлення реєстру/середовища виконання. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення/кеш може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити середовище виконання провайдера, щоб дізнатися список. -## Довідник modelIdNormalization +## Довідник `modelIdNormalization` -Використовуйте `modelIdNormalization` для дешевої, керованої провайдером нормалізації ідентифікаторів моделей, яка має відбутися до завантаження runtime провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті відповідного plugin, а не в основних таблицях вибору моделей. +Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, яке належить провайдеру та має відбутися до завантаження середовища виконання провайдера. Це тримає псевдоніми, як-от короткі назви моделей, застарілі локальні ідентифікатори провайдера та правила префіксів проксі, у маніфесті належного Plugin, а не в таблицях вибору моделей ядра. ```json { @@ -995,31 +994,31 @@ runtime більше не викликаються під час розв’яз Поля провайдера: -| Поле | Тип | Що це означає | -| ------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються так, як записані. | -| `stripPrefixes` | `string[]` | Префікси, які потрібно вилучити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксації bare-id після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | +| Поле | Тип | Що означає | +| ------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------- | +| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | +| `stripPrefixes` | `string[]` | Префікси, які треба видалити перед пошуком псевдоніма; корисно для застарілого дублювання провайдер/модель. | +| `prefixWhenBare` | `string` | Префікс, який додається, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксів для голих ідентифікаторів після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | -## Довідник providerEndpoints +## Довідник `providerEndpoints` -Використовуйте `providerEndpoints` для класифікації кінцевих точок, яку загальна політика запитів має знати до завантаження runtime провайдера. Core усе ще визначає значення кожного `endpointClass`; маніфести plugin визначають метадані хоста й базової URL-адреси. +Використовуйте `providerEndpoints` для класифікації кінцевих точок, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро й надалі визначає значення кожного `endpointClass`; маніфести Plugin володіють метаданими хоста й базової URL-адреси. Поля кінцевої точки: -| Поле | Тип | Що це означає | -| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | Відомий core-клас кінцевої точки, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, що відповідають класу кінцевої точки. | -| `hostSuffixes` | `string[]` | Суфікси хостів, що відповідають класу кінцевої точки. Додавайте префікс `.` для збігу лише із суфіксом домену. | -| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, що відповідають класу кінцевої точки. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | +| Поле | Тип | Що означає | +| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | Відомий ядру клас кінцевої точки, як-от `openrouter`, `moonshot-native` або `google-vertex`. | +| `hosts` | `string[]` | Точні імена хостів, які відповідають класу кінцевої точки. | +| `hostSuffixes` | `string[]` | Суфікси хостів, які відповідають класу кінцевої точки. Додавайте префікс `.` для зіставлення лише суфікса домену. | +| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, які відповідають класу кінцевої точки. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який треба вилучити зі збіжних хостів, щоб відкрити префікс регіону Google Vertex. | -## Довідник providerRequest +## Довідник `providerRequest` -Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Залишайте переписування payload, специфічне для поведінки, у runtime-хуках провайдера або спільних допоміжних засобах родини провайдерів. +Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, які потрібні загальній політиці запитів без завантаження середовища виконання провайдера. Переписування payload, специфічне для поведінки, залишайте в runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів. ```json { @@ -1039,15 +1038,15 @@ runtime більше не викликаються під час розв’яз Поля провайдера: -| Поле | Тип | Що це означає | -| --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- | -| `family` | `string` | Мітка родини провайдера, яку використовують загальні рішення й діагностика сумісності запитів. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності родини провайдера для спільних допоміжних засобів запитів. | -| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI; наразі `supportsStreamingUsage`. | +| Поле | Тип | Що означає | +| --------------------- | ------------ | --------------------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства провайдера, яку використовують загальні рішення сумісності запитів і діагностика. | +| `compatibilityFamily` | `"moonshot"` | Необов’язковий кошик сумісності сімейства провайдерів для спільних допоміжних засобів запитів. | +| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | -## Довідник modelPricing +## Довідник `modelPricing` -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш ціноутворення Gateway читає ці метадані без імпорту runtime-коду провайдера. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення контрольної площини до завантаження середовища виконання. Кеш ціноутворення Gateway читає ці метадані без імпорту коду середовища виконання провайдера. ```json { @@ -1070,114 +1069,120 @@ runtime більше не викликаються під час розв’яз Поля провайдера: -| Поле | Тип | Що це означає | -| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------ | -| `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не повинні отримувати ціни OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| Поле | Тип | Що означає | +| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/самостійно розміщених провайдерів, які ніколи не повинні отримувати ціни OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що це означає | -| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| Поле | Тип | Що означає | +| -------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Обробляти ідентифікатори моделей зі slash як вкладені посилання provider/model; корисно для проксі-провайдерів, як-от OpenRouter. | +| `passthroughProviderModel` | `boolean` | Обробляти ідентифікатори моделей зі слешами як вкладені посилання провайдер/модель; корисно для проксі-провайдерів, як-от OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw — це попередні метадані, керовані OpenClaw, для провайдерів, чиї plugins ще можуть бути не встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для встановлених plugins. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні installable-provider і pre-install вибору моделей використовуватимуть, коли plugin провайдера не встановлено. +Індекс провайдерів OpenClaw — це прев’ю-метадані провайдерів, якими володіє OpenClaw, для провайдерів, чиї Plugins можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. Маніфести Plugin залишаються авторитетним джерелом для встановленого Plugin. Індекс провайдерів — це внутрішній резервний контракт, який майбутні поверхні встановлюваних провайдерів і вибору моделей до встановлення використовуватимуть, коли Plugin провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. Маніфест установленого plugin `modelCatalog`. -3. Кеш каталогу моделей після явного оновлення. -4. Попередні рядки Індексу провайдерів OpenClaw. +2. `modelCatalog` маніфесту встановленого Plugin. +3. Кеш каталогу моделей з явного оновлення. +4. Прев’ю-рядки індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секретів, стану ввімкнення, runtime-хуків або актуальних даних моделей, специфічних для облікового запису. Його попередні каталоги використовують ту саму форму рядка провайдера `modelCatalog`, що й маніфести plugin, але мають обмежуватися стабільними display-метаданими, якщо поля runtime-адаптера, як-от `api`, `baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом установленого plugin. Провайдери з live-виявленням `/models` повинні записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати звичайне відображення списку або onboarding викликати API провайдера. +Індекс провайдерів не повинен містити секрети, увімкнений стан, runtime-хуки або живі дані моделей, специфічні для облікового запису. Його прев’ю-каталоги використовують ту саму форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими стабільними метаданими відображення, якщо runtime-поля адаптера, як-от `api`, `baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого Plugin. Провайдери з live-виявленням `/models` повинні записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати звичайний список або onboarding викликати API провайдера. -Записи Індексу провайдерів також можуть містити метадані installable-plugin для провайдерів, чиї plugin винесено з core або інакше ще не встановлено. Ці метадані віддзеркалюють шаблон каталогу каналів: назви пакета, npm install spec, очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати варіант installable налаштування. Щойно plugin встановлено, його маніфест має пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. +Записи індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, чий Plugin перенесено з ядра або який інакше ще не встановлено. Ці метадані віддзеркалюють шаблон каталогу каналів: назви пакета, npm install spec, очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати варіант встановлюваного налаштування. Після встановлення Plugin його маніфест перемагає, а запис індексу провайдерів для цього провайдера ігнорується. -Застарілі top-level ключі capability вважаються deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфестів більше не розглядає ці top-level поля як ownership capability. +Застарілі ключі можливостей верхнього рівня вважаються застарілими. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння можливостями. -## Маніфест проти package.json +## Маніфест і package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду Plugin | | `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, install gating, setup або метаданих каталогу | -Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте це правило: +Якщо ви не впевнені, де має бути частина метаданих, використовуйте це правило: -- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, вхідних файлів або поведінки встановлення npm, помістіть це в `package.json` ### Поля package.json, що впливають на виявлення -Деякі pre-runtime метадані plugin навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі pre-runtime метадані Plugin навмисно живуть у `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що це означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує нативні точки входу Plugin. Має залишатися всередині каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript-точки входу середовища виконання для встановлених пакетів. Має залишатися всередині каталогу пакета Plugin. | -| `openclaw.setupEntry` | Легка точка входу лише для налаштування, яку використовують під час онбордингу, відкладеного запуску каналу та виявлення стану каналу лише для читання/SecretRef. Має залишатися всередині каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібрану JavaScript-точку входу налаштування для встановлених пакетів. Потребує `setupEntry`, має існувати й має залишатися всередині каталогу пакета Plugin. | -| `openclaw.channel` | Дешева метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст вибору. | -| `openclaw.channel.commands` | Статичні нативні команди та метадані нативних skill-автозначень за замовчуванням, які використовують поверхні конфігурації, аудиту та списку команд до завантаження середовища виконання каналу. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже хтось увійшов?» без завантаження повного середовища виконання каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення для вбудованих і зовнішньо опублікованих plugins. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступні кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22` або `>=2026.5.1-beta.1`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, як-от `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт щодо нього. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналу лише для налаштування завантажитися перед повним Plugin каналу під час запуску. | +| Поле | Що це означає | +| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує нативні точки входу plugin. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу JavaScript runtime для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.setupEntry` | Легка точка входу лише для налаштування, що використовується під час onboarding, відкладеного запуску каналу та виявлення стану каналу лише для читання/SecretRef. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу JavaScript для налаштування встановлених пакетів. Вимагає `setupEntry`, має існувати та має залишатися всередині каталогу пакета plugin. | +| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані нативних команд і автоматичних стандартних значень нативних skill, що використовуються поверхнями конфігурації, аудиту та списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти на запитання "чи вже існує налаштування лише через env?" без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти на запитання "чи вже хтось увійшов у систему?" без завантаження повного runtime каналу. | +| `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugins. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, як-от `>=2026.3.22` або `>=2026.5.1-beta.1`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок integrity npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналів лише для налаштування завантажуватися перед повним plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в -онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти provider/каналу/налаштування з'являються в +onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє +onboarding, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих +варіантів. Не переміщуйте підказки встановлення в `openclaw.plugin.json`. `openclaw.install.minHostVersion` застосовується під час встановлення та завантаження -реєстру маніфестів для невбудованих джерел Plugin. Недійсні значення відхиляються; -новіші, але дійсні значення пропускають зовнішні plugins на старіших хостах. Вбудовані -джерельні plugins вважаються співверсійними з checkout хоста. +реєстру маніфестів для невбудованих джерел plugin. Недійсні значення відхиляються; +новіші, але дійсні значення пропускають зовнішні plugins на старіших хостах. Вбудовані вихідні +plugins вважаються співверсійними з checkout хоста. + +Офіційні метадані встановлення на вимогу мають використовувати `clawhubSpec`, коли plugin +опубліковано в ClawHub; onboarding розглядає це як бажане віддалене джерело та +записує факти артефакту ClawHub після встановлення. `npmSpec` залишається fallback +сумісності для пакетів, які ще не перейшли до ClawHub. Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні зовнішні записи каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення -завершувалися закритою відмовою, якщо отриманий npm-артефакт більше не відповідає -закріпленому випуску. Інтерактивний онбординг і далі пропонує довірені npm-специфікації -реєстру, зокрема голі назви пакетів і dist-tags, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені цілісністю, з відсутньою цілісністю, із невідповідністю -назви пакета та недійсні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` наявний, але немає дійсного npm-джерела, яке він може закріпити. -Коли `expectedIntegrity` наявний, потоки встановлення/оновлення застосовують його; коли -його пропущено, розв’язання реєстру записується без закріплення цілісності. +завершувалися закрито, якщо отриманий артефакт npm більше не відповідає закріпленому випуску. +Інтерактивний onboarding усе ще пропонує довірені специфікації npm registry, зокрема прості +імена пакетів і dist-tags, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені integrity, з відсутнім integrity, із невідповідністю імені пакета +та недійсні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає дійсного джерела npm, яке він може закріпити. +Коли `expectedIntegrity` присутній, +потоки встановлення/оновлення примусово застосовують його; коли його пропущено, результат registry resolution +записується без закріплення integrity. -Plugins каналів мають надавати `openclaw.setupEntry`, коли сканування стану, списку каналів +Plugins каналів мають надавати `openclaw.setupEntry`, коли перевірки стану, списку каналів або SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного -середовища виконання. Точка входу налаштування має надавати метадані каналу разом із -безпечними для налаштування адаптерами конфігурації, стану та secrets; залишайте мережеві -клієнти, слухачі Gateway і transport-середовища виконання в основній точці входу розширення. +runtime. Точка входу setup має відкривати метадані каналу плюс безпечні для setup адаптери конфігурації, +стану та secrets; мережеві клієнти, слухачі Gateway та transport runtimes тримайте в головній точці входу extension. -Поля точки входу середовища виконання не перевизначають перевірки меж пакета для -джерельних полів точки входу. Наприклад, `openclaw.runtimeExtensions` не може зробити -шлях `openclaw.extensions`, що виходить за межі, придатним до завантаження. +Поля точки входу runtime не перевизначають перевірки меж пакета для полів +вихідної точки входу. Наприклад, `openclaw.runtimeExtensions` не може зробити +шлях `openclaw.extensions`, що виходить за межі, завантажуваним. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить довільні -зламані конфігурації встановлюваними. Сьогодні він лише дозволяє потокам встановлення -відновлюватися після конкретних застарілих збоїв оновлення вбудованого Plugin, як-от -відсутній шлях вбудованого Plugin або застарілий запис `channels.` для того самого -вбудованого Plugin. Непов’язані помилки конфігурації й далі блокують встановлення та -спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить +довільні зламані конфігурації придатними до встановлення. Наразі він лише дозволяє потокам встановлення +відновлюватися після конкретних застарілих збоїв оновлення вбудованого plugin, як-от +відсутній шлях вбудованого plugin або застарілий запис `channels.` для того самого +вбудованого plugin. Непов'язані помилки конфігурації все ще блокують встановлення та спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -1193,16 +1198,14 @@ Plugins каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли потоки налаштування, doctor, стану або присутності лише для читання -потребують дешевого yes/no-зонду автентифікації до завантаження повного Plugin каналу. -Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці -метадані для автоматичного ввімкнення plugins, відновлення залежностей середовища виконання -або вирішення, чи має завантажуватися середовище виконання каналу. Цільовий експорт має бути -невеликою функцією, що читає лише збережений стан; не спрямовуйте його через повний barrel -середовища виконання каналу. +Використовуйте їх, коли setup, doctor, status або потоки присутності лише для читання потребують дешевого +auth-зондування yes/no до завантаження повного plugin каналу. Збережений auth state не є +налаштованим станом каналу: не використовуйте ці метадані для автоматичного ввімкнення plugins, +ремонту runtime dependencies або рішення, чи має завантажуватися runtime каналу. +Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не +проводьте її через повний barrel runtime каналу. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованості -лише через env: +`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок configured лише через env: ```json { @@ -1218,37 +1221,37 @@ Plugins каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли канал може відповісти про налаштований стан із env або інших -крихітних не-runtime вхідних даних. Якщо перевірці потрібне повне розв’язання конфігурації -або справжнє середовище виконання каналу, залишайте цю логіку в хуку Plugin -`config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти на configured-state з env або інших крихітних +non-runtime вхідних даних. Якщо перевірка потребує повного розв'язання конфігурації або справжнього +runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` +plugin. -## Пріоритет виявлення (дублікати ідентифікаторів Plugin) +## Пріоритет виявлення (дублікати ідентифікаторів plugin) -OpenClaw виявляє plugins із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані конфігурацією шляхи). Якщо два виявлення мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє plugins із кількох roots (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені елементи мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. Пріоритет, від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` 2. **Вбудований** — plugins, що постачаються з OpenClaw -3. **Глобальне встановлення** — plugins, установлені в глобальний корінь plugins OpenClaw +3. **Глобальне встановлення** — plugins, встановлені в глобальний root plugins OpenClaw 4. **Workspace** — plugins, виявлені відносно поточного workspace Наслідки: -- Fork або застаріла копія вбудованого Plugin у workspace не затінятиме вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення workspace. -- Відкидання дублікатів журналюються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -- Перевизначення дублікатів, вибраних конфігурацією, формулюються в діагностиці як явні перевизначення, але все одно попереджають, щоб застарілі forks і випадкові затінення залишалися видимими. +- Forked або застаріла копія вбудованого plugin у workspace не затінить вбудовану збірку. +- Щоб фактично перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладався на виявлення workspace. +- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Діагностика формулює перевизначення дублікатів, вибраних у конфігурації, як явні overrides, але все одно попереджає, щоб застарілі forks і випадкові shadowing залишалися видимими. ## Вимоги JSON Schema -- **Кожен Plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час виконання. -- Під час розширення або створення fork вбудованого Plugin із новими ключами конфігурації одночасно оновіть `configSchema` цього Plugin у `openclaw.plugin.json`. Схеми вбудованих plugins суворі, тому додавання `plugins.entries..config.myNewKey` до користувацької конфігурації без додавання `myNewKey` до `configSchema.properties` буде відхилено до завантаження середовища виконання Plugin. +- **Кожен plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Schemas перевіряються під час читання/запису конфігурації, а не під час runtime. +- Коли розширюєте або форкаєте вбудований plugin із новими ключами конфігурації, одночасно оновіть `configSchema` цього plugin у `openclaw.plugin.json`. Schemas вбудованих plugins суворі, тому додавання `plugins.entries..config.myNewKey` у конфігурацію користувача без додавання `myNewKey` до `configSchema.properties` буде відхилено до завантаження runtime plugin. -Приклад розширення схеми: +Приклад розширення schema: ```json { @@ -1264,42 +1267,42 @@ OpenClaw виявляє plugins із кількох коренів (вбудов } ``` -## Поведінка валідації +## Поведінка перевірки - Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено - маніфестом Plugin. + маніфестом plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. -- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, - валідація завершується невдало, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, а - **попередження** відображається в Doctor і журналах. + мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. +- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи schema, + перевірка завершується невдало, а Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **disabled**, конфігурація зберігається, а + **warning** показується в Doctor + logs. -Див. [довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. +Див. [Довідник конфігурації](/uk/gateway/configuration) для повної schema `plugins.*`. ## Примітки -- Маніфест є **обов’язковим для нативних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime усе ще завантажує модуль плагіна окремо; маніфест призначений лише для виявлення + валідації. -- Нативні маніфести аналізуються як JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом. +- Маніфест є **обов’язковим для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime досі завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення + перевірки. +- Нативні маніфести обробляються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все ще є об’єктом. - Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо вони не потрібні плагіну. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Оголошуйте ексклюзивний тип плагіна в цьому маніфесті. `OpenClawPluginDefinition.kind` у runtime-точці входу є застарілим і залишається лише як резервний варіант сумісності для старіших плагінів. -- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання усе ще застосовують довіру до плагіна й політику ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для runtime-метаданих майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легковажним і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні види Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Оголошуйте ексклюзивний вид Plugin у цьому маніфесті. `OpenClawPluginDefinition.kind` у runtime-вході застаріло й залишається лише як fallback сумісності для старіших 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. Внутрішня архітектура та модель можливостей. - Довідник Plugin SDK та імпорти підшляхів. + Довідник SDK для Plugin та імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-setup.md b/docs/uk/plugins/sdk-setup.md index 32e444203..952fe5e3a 100644 --- a/docs/uk/plugins/sdk-setup.md +++ b/docs/uk/plugins/sdk-setup.md @@ -1,32 +1,32 @@ --- read_when: - - Ви додаєте майстер налаштування для Plugin + - Ви додаєте майстер налаштування до Plugin - Потрібно зрозуміти setup-entry.ts порівняно з index.ts - - Ви визначаєте схеми конфігурації Plugin або метадані openclaw у package.json + - Ви визначаєте схеми конфігурації плагіна або метадані openclaw у package.json sidebarTitle: Setup and config summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json title: Налаштування та конфігурація Plugin x-i18n: - generated_at: "2026-05-02T02:49:26Z" + generated_at: "2026-05-02T14:31:50Z" model: gpt-5.5 provider: openai - source_hash: 322cf8988da686d5bf7577f9825f6f8decb738f91563e4022c14bf16dca22824 + source_hash: 9474dbbbc984e19019f7d14c7d63d944c544868407f7908df282bc7c080dc0c2 source_path: plugins/sdk-setup.md workflow: 16 --- -Довідка з пакування Plugin (метадані `package.json`), маніфестів (`openclaw.plugin.json`), записів налаштування та схем конфігурації. +Довідник із пакування плагінів (метадані `package.json`), маніфестів (`openclaw.plugin.json`), записів налаштування та схем конфігурації. -**Шукаєте покроковий посібник?** Практичні посібники розглядають пакування в контексті: [Plugin каналів](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Plugin провайдерів](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest). +**Шукаєте покроковий посібник?** Практичні посібники охоплюють пакування в контексті: [Плагіни каналів](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest). ## Метадані пакета -Ваш `package.json` потребує поля `openclaw`, яке повідомляє системі Plugin, що надає ваш Plugin: +Ваш `package.json` потребує поля `openclaw`, яке повідомляє системі плагінів, що надає ваш плагін: - + ```json { "name": "@myorg/openclaw-my-channel", @@ -44,7 +44,7 @@ x-i18n: } ``` - + ```json openclaw-clawhub-package.json { "name": "@myorg/openclaw-my-plugin", @@ -67,7 +67,7 @@ x-i18n: -Якщо ви публікуєте Plugin зовнішньо на ClawHub, ці поля `compat` і `build` є обов’язковими. Канонічні фрагменти для публікації розташовані в `docs/snippets/plugin-publish/`. +Якщо ви публікуєте плагін зовнішньо в ClawHub, ці поля `compat` і `build` є обов’язковими. Канонічні фрагменти для публікації розміщені в `docs/snippets/plugin-publish/`. ### Поля `openclaw` @@ -79,43 +79,43 @@ x-i18n: Легка точка входу лише для налаштування (необов’язково). - Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та стану. + Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та статусу. - Ідентифікатори провайдерів, зареєстровані цим Plugin. + Ідентифікатори провайдерів, які реєструє цей плагін. Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery`. - Прапорці поведінки під час запуску. + Прапорці поведінки запуску. ### `openclaw.channel` -`openclaw.channel` — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime. +`openclaw.channel` — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання. -| Поле | Тип | Що це означає | +| Поле | Тип | Що означає | | -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | | `id` | `string` | Канонічний ідентифікатор каналу. | | `label` | `string` | Основна мітка каналу. | | `selectionLabel` | `string` | Мітка вибору/налаштування, коли вона має відрізнятися від `label`. | -| `detailLabel` | `string` | Вторинна докладна мітка для розширених каталогів каналів і поверхонь стану. | +| `detailLabel` | `string` | Вторинна докладна мітка для розширених каталогів каналів і поверхонь статусу. | | `docsPath` | `string` | Шлях документації для посилань налаштування й вибору. | -| `docsLabel` | `string` | Перевизначає мітку, використану для посилань на документацію, коли вона має відрізнятися від ідентифікатора каналу. | -| `blurb` | `string` | Короткий опис для onboarding/каталогу. | +| `docsLabel` | `string` | Перевизначена мітка для посилань документації, коли вона має відрізнятися від ідентифікатора каналу. | +| `blurb` | `string` | Короткий опис для первинного налаштування/каталогу. | | `order` | `number` | Порядок сортування в каталогах каналів. | | `aliases` | `string[]` | Додаткові псевдоніми пошуку для вибору каналу. | -| `preferOver` | `string[]` | Ідентифікатори Plugin/каналів із нижчим пріоритетом, які цей канал має випереджати. | -| `systemImage` | `string` | Необов’язкова назва іконки/system-image для UI-каталогів каналів. | -| `selectionDocsPrefix` | `string` | Текст префікса перед посиланнями на документацію в поверхнях вибору. | -| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання на документацію в тексті вибору. | -| `selectionExtras` | `string[]` | Додаткові короткі рядки, додані до тексту вибору. | +| `preferOver` | `string[]` | Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати. | +| `systemImage` | `string` | Необов’язкова назва іконки/system-image для UI-каталогів каналу. | +| `selectionDocsPrefix` | `string` | Текст префікса перед посиланнями документації в поверхнях вибору. | +| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання документації в тексті вибору. | +| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються до тексту вибору. | | `markdownCapable` | `boolean` | Позначає канал як здатний працювати з Markdown для рішень щодо вихідного форматування. | -| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованого та поверхонь документації. | -| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного потоку налаштування швидкого старту `allowFrom`. | -| `forceAccountBinding` | `boolean` | Вимагати явну прив’язку облікового запису, навіть коли існує лише один обліковий запис. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Надавати перевагу пошуку сеансу під час визначення цілей оголошень для цього каналу. | +| `exposure` | `object` | Параметри видимості каналу для налаштування, списків налаштованого та поверхонь документації. | +| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного процесу налаштування швидкого старту `allowFrom`. | +| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку сеансу під час визначення цілей оголошень для цього каналу. | Приклад: @@ -149,8 +149,8 @@ x-i18n: `exposure` підтримує: -- `configured`: включати канал у поверхні списків налаштованого/стану -- `setup`: включати канал в інтерактивні засоби вибору налаштування/конфігурування +- `configured`: включати канал у налаштовані/статусні поверхні списків +- `setup`: включати канал в інтерактивні селектори налаштування/конфігурування - `docs`: позначати канал як публічний у поверхнях документації/навігації @@ -161,24 +161,25 @@ x-i18n: `openclaw.install` — це метадані пакета, а не метадані маніфесту. -| Поле | Тип | Що це означає | -| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- | -| `npmSpec` | `string` | Канонічна npm-специфікація для потоків встановлення/оновлення. | -| `localPath` | `string` | Локальний шлях розробки або шлях встановлення в комплекті. | -| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва. | -| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у формі `>=x.y.z` або `>=x.y.z-prerelease`. | -| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для закріплених встановлень. | -| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення Plugin у комплекті відновлюватися після конкретних збоїв через застарілу конфігурацію. | +| Поле | Тип | Що означає | +| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- | +| `clawhubSpec` | `string` | Канонічна специфікація ClawHub для процесів встановлення/оновлення та встановлення на вимогу під час первинного налаштування. | +| `npmSpec` | `string` | Канонічна специфікація npm для резервних процесів встановлення/оновлення. | +| `localPath` | `string` | Шлях локальної розробки або вбудованого встановлення. | +| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступно кілька джерел. | +| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у форматі `>=x.y.z` або `>=x.y.z-prerelease`. | +| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm-дистрибутива, зазвичай `sha512-...`, для закріплених встановлень. | +| `allowInvalidConfigRecovery` | `boolean` | Дає змогу процесам перевстановлення вбудованого плагіна відновлюватися після конкретних збоїв через застарілу конфігурацію. | - - Інтерактивний onboarding також використовує `openclaw.install` для поверхонь встановлення на вимогу. Якщо ваш Plugin надає вибір автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження runtime, onboarding може показати цей вибір, запропонувати npm або локальне встановлення, встановити чи ввімкнути Plugin, а потім продовжити вибраний потік. Варіанти npm для onboarding потребують довірених метаданих каталогу з реєстровим `npmSpec`; точні версії та `expectedIntegrity` є необов’язковими закріпленнями. Якщо `expectedIntegrity` присутній, потоки встановлення/оновлення забезпечують його дотримання. Зберігайте метадані "що показувати" в `openclaw.plugin.json`, а метадані "як це встановити" — у `package.json`. + + Інтерактивне первинне налаштування також використовує `openclaw.install` для поверхонь встановлення на вимогу. Якщо ваш плагін надає варіанти автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження середовища виконання, первинне налаштування може показати цей вибір, запропонувати встановлення з ClawHub, npm або локального джерела, встановити чи ввімкнути плагін, а потім продовжити вибраний процес. Варіанти ClawHub для первинного налаштування використовують `clawhubSpec` і мають перевагу, коли вони наявні; варіанти npm потребують довірених метаданих каталогу з реєстровим `npmSpec`; точні версії та `expectedIntegrity` є необов’язковими npm-закріпленнями. Якщо `expectedIntegrity` наявний, процеси встановлення/оновлення застосовують його для npm. Зберігайте метадані «що показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — у `package.json`. - - Якщо `minHostVersion` задано, і встановлення, і завантаження реєстру маніфестів для невбудованих Plugin забезпечують його дотримання. Старіші хости пропускають зовнішні Plugin; недійсні рядки версій відхиляються. Вбудовані вихідні Plugin вважаються версіонованими разом із checkout хоста. + + Якщо `minHostVersion` задано, і встановлення, і завантаження невбудованого реєстру маніфестів застосовують це обмеження. Старіші хости пропускають зовнішні плагіни; недійсні рядки версій відхиляються. Вважається, що вбудовані вихідні плагіни мають ту саму версію, що й робоча копія хоста. - - Для закріплених npm-встановлень зберігайте точну версію в `npmSpec` і додайте очікувану цілісність артефакта: + + Для закріплених встановлень npm зберігайте точну версію в `npmSpec` і додайте очікувану цілісність артефакту: ```json { @@ -193,14 +194,14 @@ x-i18n: ``` - - `allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення Plugin у комплекті, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях Plugin у комплекті або застарілий запис `channels.` для того самого Plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення все одно безпечно завершується помилкою й повідомляє оператору запустити `openclaw doctor --fix`. + + `allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення вбудованих плагінів, щоб перевстановлення/налаштування могло виправляти відомі залишки після оновлення, як-от відсутній шлях вбудованого плагіна або застарілий запис `channels.` для того самого плагіна. Якщо конфігурація зламана з непов’язаних причин, встановлення все одно завершується відмовою й повідомляє оператору запустити `openclaw doctor --fix`. ### Відкладене повне завантаження -Plugin каналів можуть увімкнути відкладене завантаження за допомогою: +Плагіни каналів можуть увімкнути відкладене завантаження так: ```json { @@ -214,17 +215,17 @@ Plugin каналів можуть увімкнути відкладене за } ``` -Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до початку прослуховування, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування. +Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску перед прослуховуванням, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування. -Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи gateway). Якщо повна точка входу володіє потрібними можливостями запуску, залиште поведінку за замовчуванням. +Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи Gateway). Якщо повна точка входу володіє потрібними можливостями запуску, залиште стандартну поведінку. -Якщо ваша точка входу setup/full реєструє gateway RPC-методи, тримайте їх на префіксі, специфічному для Plugin. Зарезервовані основні простори імен адміністратора (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності core і завжди вирішуються до `operator.admin`. +Якщо ваша точка входу setup/full реєструє RPC-методи Gateway, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності ядра й завжди розв’язуються до `operator.admin`. ## Маніфест Plugin -Кожен нативний Plugin має постачати `openclaw.plugin.json` у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду Plugin. +Кожен нативний плагін має містити `openclaw.plugin.json` у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду плагіна. ```json { @@ -244,7 +245,7 @@ Plugin каналів можуть увімкнути відкладене за } ``` -Для Plugin каналів додайте `kind` і `channels`: +Для плагінів каналів додайте `kind` і `channels`: ```json { @@ -259,7 +260,7 @@ Plugin каналів можуть увімкнути відкладене за } ``` -Навіть Plugin без конфігурації мають постачати схему. Порожня схема є дійсною: +Навіть плагіни без конфігурації мають містити схему. Порожня схема є дійсною: ```json { @@ -271,11 +272,11 @@ Plugin каналів можуть увімкнути відкладене за } ``` -Див. [Маніфест Plugin](/uk/plugins/manifest) для повної довідки зі схеми. +Див. [Маніфест Plugin](/uk/plugins/manifest), щоб отримати повну довідку зі схеми. -## Публікація ClawHub +## Публікація в ClawHub -Для пакетів Plugin використовуйте специфічну для пакетів команду ClawHub: +Для пакетів плагінів використовуйте специфічну для пакета команду ClawHub: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -288,7 +289,7 @@ clawhub package publish your-org/your-plugin ## Запис налаштування -Файл `setup-entry.ts` є легкою альтернативою `index.ts`, яку OpenClaw завантажує, коли потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, перевірка вимкненого каналу). +Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (первинне налаштування, відновлення конфігурації, інспекція вимкненого каналу). ```typescript // setup-entry.ts @@ -298,65 +299,65 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Це уникає завантаження важкого коду runtime (криптографічних бібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування. +Це дає змогу не завантажувати важкий код виконання (криптографічні бібліотеки, реєстрації CLI, фонові служби) під час потоків налаштування. -Вбудовані канали робочої області, які тримають безпечні для налаштування експорти в супровідних модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт `runtime`, щоб runtime-зв’язування під час налаштування залишалося легким і явним. +Вбудовані канали робочої області, які тримають безпечні для налаштування експорти в допоміжних модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт `runtime`, щоб зв’язування середовища виконання під час налаштування залишалося легким і явним. - - - Канал вимкнено, але йому потрібні поверхні налаштування/онбордингу. + + - Канал вимкнено, але йому потрібні поверхні налаштування/первинного налаштування. - Канал увімкнено, але не налаштовано. - Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`). - + - Об’єкт Plugin каналу (через `defineSetupPluginEntry`). - - Будь-які HTTP-маршрути, потрібні до запуску прослуховування Gateway. - - Будь-які методи Gateway, потрібні під час запуску. + - Будь-які HTTP-маршрути, потрібні до прослуховування gateway. + - Будь-які методи gateway, потрібні під час запуску. - Ці стартові методи Gateway все одно мають уникати зарезервованих core-просторів імен адміністрування, як-от `config.*` або `update.*`. + Ці методи gateway запуску все одно мають уникати зарезервованих просторів імен адміністрування ядра, як-от `config.*` або `update.*`. - - - Реєстрацій CLI. - - Фонових сервісів. - - Важких імпортів runtime (криптографія, SDK). - - Методів Gateway, потрібних лише після запуску. + + - Реєстрації CLI. + - Фонові служби. + - Важкі імпорти середовища виконання (crypto, SDK). + - Методи Gateway, потрібні лише після запуску. -### Вузькі імпорти допоміжних засобів налаштування +### Вузькі імпорти помічників налаштування -Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшої обгортки `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: +Для гарячих шляхів лише налаштування надавайте перевагу вузьким швам помічників налаштування замість ширшого парасолькового `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: -| Шлях імпорту | Для чого використовувати | Ключові експорти | +| Шлях імпорту | Для чого використовувати | Ключові експорти | | ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | runtime-допоміжні засоби під час налаштування, які залишаються доступними в `setupEntry` / відкладеному запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-runtime` | помічники середовища виконання під час налаштування, що залишаються доступними в `setupEntry` / відкладеному запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікового запису з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | допоміжні засоби CLI/архівів/документації для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| `plugin-sdk/setup-tools` | помічники CLI/archive/docs для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний інструментарій налаштування, зокрема допоміжні засоби патчів конфігурації, як-от `moveSingleAccountChannelSectionToDefaultAccount(...)`. +Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний набір інструментів налаштування, зокрема помічники виправлення конфігурації, як-от `moveSingleAccountChannelSectionToDefaultAccount(...)`. -Адаптери патчів налаштування залишаються безпечними для імпорту на гарячому шляху. Їхній пошук поверхні контракту вбудованого підвищення одного облікового запису є лінивим, тож імпорт `plugin-sdk/setup-runtime` не завантажує заздалегідь виявлення вбудованої поверхні контракту до фактичного використання адаптера. +Адаптери виправлень налаштування безпечні для гарячого шляху під час імпорту. Їхній вбудований пошук поверхні контракту просування одного облікового запису є ледачим, тому імпорт `plugin-sdk/setup-runtime` не завантажує завчасно виявлення вбудованої поверхні контракту до фактичного використання адаптера. -### Підвищення одного облікового запису, що належить каналу +### Просування одного облікового запису, яким володіє канал -Коли канал переходить від конфігурації одного облікового запису верхнього рівня до `channels..accounts.*`, стандартна спільна поведінка переносить підвищені значення, прив’язані до облікового запису, в `accounts.default`. +Коли канал переходить від конфігурації верхнього рівня для одного облікового запису до `channels..accounts.*`, стандартна спільна поведінка переносить просунуті значення області облікового запису в `accounts.default`. -Вбудовані канали можуть звузити або перевизначити це підвищення через свою поверхню контракту налаштування: +Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню контракту налаштування: -- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перенести до підвищеного облікового запису -- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці ключі переносяться до підвищеного облікового запису; спільні ключі політики/доставки залишаються в корені каналу -- `resolveSingleAccountPromotionTarget(...)`: вибирає, який наявний обліковий запис отримує підвищені значення +- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які мають перейти до просунутого облікового запису +- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці ключі переходять до просунутого облікового запису; спільні ключі політики/доставки залишаються в корені каналу +- `resolveSingleAccountPromotionTarget(...)`: вибрати, який наявний обліковий запис отримає просунуті значення -Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо `defaultAccount` вказує на наявний неканонічний ключ, як-от `Ops`, підвищення зберігає цей обліковий запис замість створення нового запису `accounts.default`. +Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо `defaultAccount` вказує на наявний неканонічний ключ, як-от `Ops`, просування зберігає цей обліковий запис замість створення нового запису `accounts.default`. ## Схема конфігурації -Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі налаштовують plugins через: +Конфігурація Plugin перевіряється за JSON Schema у вашому manifest. Користувачі налаштовують plugins через: ```json5 { @@ -387,7 +388,7 @@ Matrix є поточним вбудованим прикладом. Якщо в } ``` -### Побудова схем конфігурації каналу +### Побудова схем конфігурації каналів Використовуйте `buildChannelConfigSchema`, щоб перетворити схему Zod на обгортку `ChannelConfigSchema`, яку використовують артефакти конфігурації, що належать Plugin: @@ -405,11 +406,11 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -Для сторонніх plugins контракт холодного шляху все ще є маніфестом Plugin: віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб схема конфігурації, налаштування й UI-поверхні могли перевіряти `channels.` без завантаження runtime-коду. +Для сторонніх plugins контракт холодного шляху все ще є manifest Plugin: віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб схема конфігурації, налаштування та поверхні UI могли інспектувати `channels.` без завантаження коду виконання. ## Майстри налаштування -Plugins каналів можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. Майстер є об’єктом `ChannelSetupWizard` у `ChannelPlugin`: +Plugins каналів можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. Майстер — це об’єкт `ChannelSetupWizard` на `ChannelPlugin`: ```typescript import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup"; @@ -442,14 +443,14 @@ const setupWizard: ChannelSetupWizard = { }; ``` -Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` тощо. Повні приклади дивіться у вбудованих пакетах Plugin (наприклад, Plugin Discord `src/channel.setup.ts`). +Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інше. Повні приклади дивіться у вбудованих пакетах plugins (наприклад, Plugin Discord `src/channel.setup.ts`). - - Для запитів списку дозволених DM, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. + + Для prompts списку дозволених DM, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, надавайте перевагу спільним помічникам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. - Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу `createStandardChannelSetupStatus(...)` з `openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у кожному Plugin. + Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, надавайте перевагу `createStandardChannelSetupStatus(...)` з `openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у кожному Plugin. Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте `createOptionalChannelSetupSurface` з `openclaw/plugin-sdk/channel-setup`: @@ -466,18 +467,18 @@ const setupWizard: ChannelSetupWizard = { // Returns { setupAdapter, setupWizard } ``` - `plugin-sdk/channel-setup` також надає нижчерівневі побудовники `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї поверхні необов’язкового встановлення. + `plugin-sdk/channel-setup` також надає нижчорівневі конструктори `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення. - Згенерований необов’язковий адаптер/майстер закрито відмовляє для реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на документацію, коли задано `docsPath`. + Згенерований необов’язковий адаптер/майстер закривається з відмовою для реальних записів конфігурації. Вони повторно використовують одне повідомлення про потрібне встановлення в `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на docs, коли задано `docsPath`. - - Для UI налаштування на основі binary віддавайте перевагу спільним делегованим допоміжним засобам замість копіювання того самого зв’язування binary/статусу в кожен канал: + + Для UI налаштування на основі binary надавайте перевагу спільним делегованим помічникам замість копіювання того самого зв’язувального коду binary/status у кожен канал: - - `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише мітками, підказками, оцінками та виявленням binary - - `createCliPathTextInput(...)` для текстових полів на основі шляху - - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` потрібно ліниво переспрямовувати до важчого повного майстра - - `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише делегувати рішення `textInputs[*].shouldPrompt` + - `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише мітками, підказками, оцінками та виявленням binary + - `createCliPathTextInput(...)` для текстових введень на основі шляху + - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ледаче переспрямувати до важчого повного майстра + - `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише делегувати рішення `textInputs[*].shouldPrompt` @@ -487,12 +488,12 @@ const setupWizard: ChannelSetupWizard = { **Зовнішні plugins:** опублікуйте в [ClawHub](/uk/tools/clawhub), потім встановіть: - + ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` - OpenClaw спочатку пробує ClawHub і автоматично переходить до npm у разі невдачі. + OpenClaw спочатку пробує ClawHub і автоматично повертається до npm. @@ -500,9 +501,9 @@ const setupWizard: ChannelSetupWizard = { openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - - Використовуйте npm, коли пакет ще не переміщено до ClawHub або коли вам потрібен - прямий шлях встановлення npm під час міграції: + + Використовуйте npm, коли пакет ще не переміщено до ClawHub або коли під час міграції потрібен + прямий шлях встановлення npm: ```bash openclaw plugins install npm:@myorg/openclaw-my-plugin @@ -520,17 +521,17 @@ openclaw plugins install ``` -Для встановлень із npm `openclaw plugins install` встановлює пакет у `~/.openclaw/npm` з вимкненими lifecycle-скриптами. Тримайте дерева залежностей Plugin чистими JS/TS і уникайте пакетів, які потребують `postinstall`-збірок. +Для інсталяцій із джерелом npm `openclaw plugins install` встановлює пакет у `~/.openclaw/npm` з вимкненими сценаріями життєвого циклу. Тримайте дерева залежностей Plugin суто JS/TS і уникайте пакетів, які потребують збірок `postinstall`. -Запуск Gateway не встановлює залежності Plugin. Потоки встановлення npm/git/ClawHub відповідають за збіжність залежностей; локальні plugins уже мають мати встановлені свої залежності. +Запуск Gateway не встановлює залежності Plugin. Потоки встановлення npm/git/ClawHub відповідають за узгодження залежностей; локальні plugins уже повинні мати встановлені залежності. -Метадані вбудованого пакета задаються явно, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності мають бути в пакеті Plugin, якому вони належать; запуск пакетованого OpenClaw ніколи не виправляє й не дзеркалить залежності Plugin. +Метадані вбудованого пакета є явними, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності мають бути в пакеті Plugin, якому вони належать; запуск упакованого OpenClaw ніколи не відновлює й не дзеркалить залежності Plugin. ## Пов’язане - [Створення plugins](/uk/plugins/building-plugins) — покроковий посібник для початку роботи -- [Маніфест Plugin](/uk/plugins/manifest) — повна довідка зі схеми маніфесту -- [Точки входу SDK](/uk/plugins/sdk-entrypoints) — `definePluginEntry` та `defineChannelPluginEntry` +- [Маніфест Plugin](/uk/plugins/manifest) — повний довідник схеми маніфесту +- [Точки входу SDK](/uk/plugins/sdk-entrypoints) — `definePluginEntry` і `defineChannelPluginEntry`