diff --git a/docs/uk/concepts/model-failover.md b/docs/uk/concepts/model-failover.md index b50d0feae..c325246d4 100644 --- a/docs/uk/concepts/model-failover.md +++ b/docs/uk/concepts/model-failover.md @@ -1,26 +1,26 @@ --- read_when: - - Діагностика ротації профілів автентифікації, періодів охолодження або поведінки резервного перемикання моделей - - Оновлення правил резервного перемикання для профілів автентифікації або моделей - - Розуміння того, як перевизначення моделей сеансу взаємодіють із повторними спробами резервного перемикання + - Діагностика ротації auth profiles, cooldown-періодів або поведінки резервного переходу між моделями + - Оновлення правил резервного переходу для auth profiles або моделей + - Розуміння того, як перевизначення моделі сеансу взаємодіють із повторними спробами резервного переходу sidebarTitle: Model failover -summary: Як OpenClaw ротує профілі автентифікації та виконує резервне перемикання між моделями -title: Резервне перемикання моделей +summary: Як OpenClaw змінює auth profiles по черзі та виконує резервний перехід між моделями +title: Резервний перехід між моделями x-i18n: - generated_at: "2026-04-27T08:25:08Z" + generated_at: "2026-04-27T08:31:07Z" model: gpt-5.4 provider: openai - source_hash: b652e0bfb30aa698f0badbd341e615eb110254ca08abb1896189e95b0f9d4c61 + source_hash: 7b6fd539fddce6f7dfee9bf04076026b09fb1b84c5c170578bca9643e0105bd4 source_path: concepts/model-failover.md workflow: 15 --- OpenClaw обробляє збої у два етапи: -1. **Ротація профілів автентифікації** в межах поточного провайдера. -2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`. +1. **Ротація auth profiles** у межах поточного провайдера. +2. **Резервний перехід між моделями** до наступної моделі в `agents.defaults.model.fallbacks`. -У цьому документі пояснюються правила виконання під час роботи та дані, на яких вони базуються. +Цей документ пояснює правила виконання під час роботи та дані, на яких вони базуються. ## Потік виконання @@ -28,45 +28,46 @@ OpenClaw обробляє збої у два етапи: - Визначте активну модель сеансу та налаштування профілю автентифікації. Перевизначення сеансу з `modelOverrideSource: "auto"` походить із попереднього резервного перемикання, тому наступний запуск спочатку очищує його та знову пробує налаштовану основну модель; перевизначення, вибрані користувачем, залишаються закріпленими. + Визначте активну модель сеансу та налаштування пріоритету auth-profile. - Побудуйте ланцюжок кандидатів моделей на основі поточної вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у заданому порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення. + Побудуйте ланцюжок кандидатів моделей із поточної вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у вказаному порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення. - Спробуйте поточного провайдера з правилами ротації/охолодження профілів автентифікації. + Спробуйте поточного провайдера з правилами ротації/cooldown для auth-profile. - - Якщо цей провайдер вичерпано через помилку, що варта резервного перемикання, перейдіть до наступного кандидата моделі. + + Якщо ресурси цього провайдера вичерпано через помилку, що допускає резервний перехід, перейдіть до наступної моделі-кандидата. - - Збережіть вибране перевизначення резервного перемикання до початку повторної спроби, щоб інші читачі сеансу бачили того самого провайдера/модель, яких виконавець ось-ось використає. Збережене перевизначення моделі позначається як `modelOverrideSource: "auto"`. + + Збережіть вибране перевизначення резервного переходу до початку повторної спроби, щоб інші читачі стану сеансу бачили того самого провайдера/модель, яких виконавець збирається використати. Збережене перевизначення моделі позначається як `modelOverrideSource: "auto"`. - - Якщо кандидат резервного перемикання не вдається, відкочуйте лише ті поля перевизначення сеансу, що належать резервному перемиканню, якщо вони все ще відповідають цьому невдалому кандидату. + + Якщо кандидат резервного переходу завершується з помилкою, відкочуйте лише поля перевизначення сеансу, що належать резервному переходу, якщо вони все ще відповідають цьому невдалому кандидату. - - Якщо всі кандидати завершилися невдачею, викиньте `FallbackSummaryError` із деталями по кожній спробі та найближчим часом завершення охолодження, якщо він відомий. + + Якщо кожен кандидат завершується помилкою, викиньте `FallbackSummaryError` із деталями по кожній спробі та найближчим моментом завершення cooldown, якщо він відомий. -Це навмисно вужче, ніж «зберегти та відновити весь сеанс». Виконавець відповіді зберігає лише поля вибору моделі, якими він керує для резервного перемикання: +Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Виконавець відповіді зберігає лише поля вибору моделі, якими він володіє для резервного переходу: - `providerOverride` - `modelOverride` +- `modelOverrideSource` - `authProfileOverride` - `authProfileOverrideSource` - `authProfileOverrideCompactionCount` -Це запобігає ситуації, коли невдала повторна спроба резервного перемикання перезаписує новіші несуміжні зміни сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби. +Це запобігає ситуації, коли невдала повторна спроба резервного переходу перезаписує новіші, не пов’язані із цим зміни сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби. ## Сховище автентифікації (ключі + OAuth) -OpenClaw використовує **профілі автентифікації** як для API-ключів, так і для OAuth-токенів. +OpenClaw використовує **auth profiles** як для API-ключів, так і для OAuth-токенів. - Секрети зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (застарілий шлях: `~/.openclaw/agent/auth-profiles.json`). - Стан маршрутизації автентифікації під час роботи зберігається в `~/.openclaw/agents//agent/auth-state.json`. -- Конфігурації `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів). +- Конфігурація `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів). - Застарілий файл OAuth лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання). Докладніше: [OAuth](/uk/concepts/oauth) @@ -78,16 +79,16 @@ OpenClaw використовує **профілі автентифікації* ## Ідентифікатори профілів -OAuth-входи створюють окремі профілі, щоб могли співіснувати кілька облікових записів. +OAuth-входи створюють окремі профілі, щоб кілька облікових записів могли співіснувати. - За замовчуванням: `provider:default`, якщо email недоступний. - OAuth з email: `provider:` (наприклад, `google-antigravity:user@gmail.com`). -Профілі зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` у розділі `profiles`. +Профілі зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` у секції `profiles`. ## Порядок ротації -Коли провайдер має кілька профілів, OpenClaw вибирає порядок так: +Коли провайдер має кілька профілів, OpenClaw визначає порядок так: @@ -97,73 +98,73 @@ OAuth-входи створюють окремі профілі, щоб могл `auth.profiles`, відфільтровані за провайдером. - Записи в `auth-profiles.json` для провайдера. + Записи в `auth-profiles.json` для цього провайдера. -Якщо явний порядок не налаштовано, OpenClaw використовує порядок round‑robin: +Якщо явний порядок не налаштовано, OpenClaw використовує порядок round-robin: -- **Основний ключ:** тип профілю (**OAuth перед API-ключами**). -- **Другорядний ключ:** `usageStats.lastUsed` (найстаріший спочатку в межах кожного типу). -- **Профілі в охолодженні/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим часом завершення. +- **Первинний ключ:** тип профілю (**OAuth перед API-ключами**). +- **Вторинний ключ:** `usageStats.lastUsed` (найстаріші спочатку в межах кожного типу). +- **Профілі в cooldown/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим завершенням строку. -### Закріплення сеансу (сприятливе для кешу) +### Прив’язка до сеансу (дружньо до кешу) -OpenClaw **закріплює вибраний профіль автентифікації на рівні сеансу**, щоб кеші провайдера залишалися прогрітими. Він **не** виконує ротацію при кожному запиті. Закріплений профіль використовується повторно, доки: +OpenClaw **закріплює вибраний auth profile за кожним сеансом**, щоб кеші провайдера залишалися «теплими». Він **не** виконує ротацію для кожного запиту. Закріплений профіль використовується повторно, доки: - сеанс не буде скинуто (`/new` / `/reset`) -- не завершиться Compaction (лічильник compaction збільшиться) -- профіль не перейде в охолодження / не буде вимкнений +- не завершиться Compaction (лічильник compaction збільшується) +- профіль не перейде в cooldown/не буде вимкнений -Ручний вибір через `/model …@` задає **перевизначення користувача** для цього сеансу й не ротуватиметься автоматично, доки не почнеться новий сеанс. +Ручний вибір через `/model …@` встановлює **користувацьке перевизначення** для цього сеансу і не ротуватиметься автоматично, доки не почнеться новий сеанс. -Автоматично закріплені профілі (вибрані маршрутизатором сеансу) розглядаються як **уподобання**: вони пробуються першими, але OpenClaw може переключитися на інший профіль у разі лімітів швидкості/тайм-аутів. Профілі, закріплені користувачем, залишаються зафіксованими на цьому профілі; якщо він не спрацьовує і налаштовано резервне перемикання моделей, OpenClaw переходить до наступної моделі замість зміни профілю. +Автоматично закріплені профілі (вибрані маршрутизатором сеансу) вважаються **перевагою**: їх пробують першими, але OpenClaw може переключитися на інший профіль у разі rate limit/тайм-аутів. Профілі, закріплені користувачем, залишаються жорстко прив’язаними до цього профілю; якщо він завершується помилкою і налаштовано резервні переходи між моделями, OpenClaw переходить до наступної моделі замість перемикання профілів. ### Чому OAuth може «виглядати втраченим» -Якщо для одного й того самого провайдера у вас є і OAuth-профіль, і профіль API-ключа, round‑robin може перемикатися між ними між повідомленнями, якщо профіль не закріплено. Щоб примусово використовувати один профіль: +Якщо для одного й того самого провайдера у вас є і OAuth-профіль, і профіль з API-ключем, round-robin може перемикатися між ними між повідомленнями, якщо профіль не закріплено. Щоб примусово використовувати один профіль: - Закріпіть його через `auth.order[provider] = ["provider:profileId"]`, або -- Використовуйте перевизначення для конкретного сеансу через `/model …` із перевизначенням профілю (де це підтримується вашим UI/поверхнею чату). +- Використайте перевизначення для конкретного сеансу через `/model …` із перевизначенням профілю (коли це підтримується вашим інтерфейсом/UI або поверхнею чату). -## Періоди охолодження +## Cooldown -Коли профіль завершується помилкою через автентифікацію/ліміти швидкості (або через тайм-аут, схожий на обмеження швидкості), OpenClaw позначає його як такий, що перебуває в охолодженні, і переходить до наступного профілю. +Коли профіль завершується помилкою через збої автентифікації/rate limit (або тайм-аут, схожий на rate limiting), OpenClaw переводить його в cooldown і переходить до наступного профілю. - - Ця категорія лімітів швидкості ширша за звичайний `429`: вона також включає повідомлення провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні обмеження в межах вікна використання, як-от `weekly/monthly limit reached`. + + Категорія rate limit ширша, ніж просто `429`: вона також включає повідомлення провайдерів на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні ліміти вікна використання, як-от `weekly/monthly limit reached`. - Помилки формату/некоректного запиту (наприклад, помилки валідації ідентифікатора виклику інструмента Cloud Code Assist) вважаються такими, що варті резервного перемикання, і використовують ті самі періоди охолодження. Помилки stop-reason у стилі OpenAI-compatible, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали тайм-ауту/резервного перемикання. + Помилки формату/некоректного запиту (наприклад, помилки валідації ідентифікатора виклику інструмента Cloud Code Assist) вважаються такими, що допускають резервний перехід, і використовують ті самі cooldown. Помилки OpenAI-compatible stop-reason, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали timeout/failover. - Загальний текст серверних помилок також може потрапляти до цієї категорії тайм-аутів, якщо джерело відповідає відомому тимчасовому шаблону. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається таким, що варте резервного перемикання, для кожного провайдера, оскільки pi-ai повертає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON-повідомлення `api_error` із тимчасовим серверним текстом, таким як `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також вважаються тайм-аутами, що варті резервного перемикання. + Загальний серверний текст також може потрапити до цієї категорії timeout, якщо джерело відповідає відомому шаблону тимчасового збою. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається таким, що допускає резервний перехід, для всіх провайдерів, оскільки pi-ai видає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON-повідомлення `api_error` з тимчасовим серверним текстом, як-от `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також розглядаються як timeout, що допускають резервний перехід. - Загальний upstream-текст, специфічний для OpenRouter, як-от просте `Provider returned error`, вважається тайм-аутом лише тоді, коли контекст провайдера справді є OpenRouter. Загальний внутрішній текст резервного перемикання, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервне перемикання. + Специфічний для OpenRouter загальний текст upstream-помилки на кшталт простого `Provider returned error` вважається timeout лише тоді, коли контекст провайдера справді OpenRouter. Загальний внутрішній текст резервного переходу, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервний перехід. - - Деякі SDK провайдерів інакше можуть заснути на довге вікно `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на базі Stainless, як-от Anthropic і OpenAI, OpenClaw за замовчуванням обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і негайно повертає довші відповіді, придатні до повтору, щоб цей шлях резервного перемикання міг спрацювати. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry). + + Деякі SDK провайдерів інакше можуть чекати довге вікно `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на базі Stainless, як-от Anthropic і OpenAI, OpenClaw за замовчуванням обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і одразу повертає довші відповіді, які можна повторити, щоб цей шлях резервного переходу міг спрацювати. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry). - - Періоди охолодження через ліміти швидкості також можуть бути прив’язані до моделі: + + Cooldown rate limit також можуть бути прив’язані до моделі: - - OpenClaw записує `cooldownModel` для збоїв через ліміти швидкості, коли ідентифікатор моделі, що завершилася помилкою, відомий. - - Сусідню модель у того самого провайдера все ще можна спробувати, коли охолодження прив’язане до іншої моделі. - - Вікна блокування через білінг/вимкнення все одно блокують увесь профіль для всіх моделей. + - OpenClaw записує `cooldownModel` для помилок rate limit, коли ідентифікатор моделі, що завершилася помилкою, відомий. + - Сусідню модель у того самого провайдера все ще можна спробувати, якщо cooldown прив’язаний до іншої моделі. + - Вікна білінгу/вимкнення все одно блокують увесь профіль для всіх моделей. -Періоди охолодження використовують експоненційне збільшення затримки: +Для cooldown використовується експоненційне збільшення інтервалу: - 1 хвилина - 5 хвилин - 25 хвилин - 1 година (максимум) -Стан зберігається в `auth-state.json` у розділі `usageStats`: +Стан зберігається в `auth-state.json` у `usageStats`: ```json { @@ -179,12 +180,12 @@ OpenClaw **закріплює вибраний профіль автентифі ## Вимкнення через білінг -Збої через білінг/кредити (наприклад, «недостатньо кредитів» / «занадто низький кредитний баланс») вважаються такими, що варті резервного перемикання, але зазвичай вони не є тимчасовими. Замість короткого періоду охолодження OpenClaw позначає профіль як **вимкнений** (із довшим backoff) і переходить до наступного профілю/провайдера. +Збої білінгу/кредитів (наприклад, «insufficient credits» / «credit balance too low») вважаються такими, що допускають резервний перехід, але зазвичай вони не є тимчасовими. Замість короткого cooldown OpenClaw позначає профіль як **disabled** (із довшим backoff) і переходить до наступного профілю/провайдера. -Не кожна відповідь, схожа на білінгову, є `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст, пов’язаний із білінгом, у білінговому сценарії навіть тоді, коли провайдер натомість повертає `401` або `403`, але matchers, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`). +Не кожна відповідь, схожа на білінгову, має код `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст про білінг у категорії billing навіть тоді, коли провайдер натомість повертає `401` або `403`, але спеціалізовані матчери провайдера залишаються обмеженими тим провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`). -Тим часом тимчасові помилки `402`, пов’язані з вікном використання та лімітами витрат організації/робочого простору, класифікуються як `rate_limit`, коли повідомлення виглядає придатним до повтору (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого охолодження/резервного перемикання, а не довгого шляху вимкнення через білінг. +Тим часом тимчасові помилки `402`, пов’язані з вікном використання, а також лімітами витрат організації/робочого простору, класифікуються як `rate_limit`, коли повідомлення виглядає як таке, що допускає повторну спробу (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого cooldown/резервного переходу замість шляху довгого вимкнення через білінг. Стан зберігається в `auth-state.json`: @@ -202,118 +203,118 @@ OpenClaw **закріплює вибраний профіль автентифі Значення за замовчуванням: -- Backoff для білінгу починається з **5 годин**, подвоюється після кожного збою через білінг і обмежується **24 годинами**. -- Лічильники backoff скидаються, якщо профіль не завершувався помилкою протягом **24 годин** (можна налаштувати). -- Повторні спроби при перевантаженні дозволяють **1 ротацію профілю того самого провайдера** перед резервним перемиканням моделі. +- Backoff для білінгу починається з **5 годин**, подвоюється після кожного збою білінгу й обмежується **24 годинами**. +- Лічильники backoff скидаються, якщо профіль не мав збоїв протягом **24 годин** (можна налаштувати). +- Повторні спроби при перевантаженні дозволяють **1 ротацію профілю того самого провайдера** перед резервним переходом між моделями. - Повторні спроби при перевантаженні за замовчуванням використовують backoff **0 мс**. -## Резервне перемикання моделей +## Резервний перехід між моделями -Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до збоїв автентифікації, лімітів швидкості та тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервне перемикання). +Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до збоїв автентифікації, rate limit і тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервний перехід). -Помилки перевантаження та лімітів швидкості обробляються агресивніше, ніж періоди охолодження через білінг. За замовчуванням OpenClaw дозволяє одну повторну спробу профілю автентифікації в межах того самого провайдера, а потім без очікування переходить до наступної налаштованої резервної моделі. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють до цієї категорії перевантаження. Це можна налаштувати через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. +Помилки перевантаження та rate limit обробляються агресивніше, ніж cooldown для білінгу. За замовчуванням OpenClaw дозволяє одну повторну спробу auth-profile у того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють до цієї категорії перевантаження. Це можна налаштувати через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. -Коли запуск починається з перевизначення моделі (hooks або CLI), резервні перемикання все одно завершуються на `agents.defaults.model.primary` після спроб усіх налаштованих резервних варіантів. +Коли запуск починається з перевизначення моделі (hooks або CLI), резервні переходи все одно завершуються на `agents.defaults.model.primary` після спроб будь-яких налаштованих резервних варіантів. ### Правила ланцюжка кандидатів -OpenClaw будує список кандидатів із поточно запитаного `provider/model` та налаштованих резервних варіантів. +OpenClaw будує список кандидатів із поточно запитаного `provider/model` плюс налаштовані резервні варіанти. - Запитана модель завжди перша. - Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за allowlist моделей. Вони вважаються явним наміром оператора. - - Якщо поточний запуск уже використовує налаштований резервний варіант у межах тієї самої сім’ї провайдерів, OpenClaw продовжує використовувати весь налаштований ланцюжок. - - Якщо поточний запуск використовує іншого провайдера, ніж указано в конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервного перемикання, OpenClaw не додає несуміжні налаштовані резервні варіанти від іншого провайдера. - - Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг повернутися до звичайного стандартного значення після вичерпання попередніх кандидатів. + - Якщо поточний запуск уже працює на налаштованій резервній моделі в тій самій сім’ї провайдера, OpenClaw продовжує використовувати весь налаштований ланцюжок. + - Якщо поточний запуск використовує іншого провайдера, ніж у конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервних переходів, OpenClaw не додає не пов’язані налаштовані резервні варіанти від іншого провайдера. + - Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг зрештою повернутися до звичайного стандартного варіанту після вичерпання попередніх кандидатів. -### Які помилки просувають резервне перемикання +### Які помилки просувають резервний перехід - збоїв автентифікації - - лімітів швидкості та вичерпання періодів охолодження + - rate limit і вичерпання cooldown - помилок перевантаження/зайнятості провайдера - - помилок резервного перемикання, схожих на тайм-аут + - помилок резервного переходу, схожих на timeout - вимкнень через білінг - - `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного перемикання, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб + - `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного переходу, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб - інших нерозпізнаних помилок, коли ще залишаються кандидати - - явних переривань, які не мають форми тайм-ауту/резервного перемикання + - явних переривань, які не схожі на timeout/резервний перехід - помилок переповнення контексту, які мають залишатися в межах логіки Compaction/повторних спроб (наприклад, `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model` або `ollama error: context length exceeded`) - фінальної невідомої помилки, коли кандидатів більше не залишилося -### Поведінка пропуску охолодження та пробних спроб +### Поведінка пропуску cooldown порівняно з probe -Коли всі профілі автентифікації для провайдера вже перебувають в охолодженні, OpenClaw не пропускає цього провайдера назавжди автоматично. Він приймає рішення окремо для кожного кандидата: +Коли всі auth profiles для провайдера вже перебувають у cooldown, OpenClaw не пропускає цього провайдера автоматично назавжди. Він приймає рішення окремо для кожного кандидата: - - Стійкі збої автентифікації негайно пропускають усього провайдера. - - Вимкнення через білінг зазвичай призводять до пропуску, але основного кандидата все ще можна пробно перевірити з throttle, щоб відновлення було можливим без перезапуску. - - Основного кандидата можна пробно перевірити ближче до завершення охолодження, з throttle на рівні провайдера. - - Сусідні резервні варіанти того самого провайдера можна пробувати попри охолодження, коли збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо важливо, коли ліміт швидкості прив’язаний до моделі, а сусідня модель може відновитися негайно. - - Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера за один запуск резервного перемикання, щоб один провайдер не затримував резервне перемикання між провайдерами. + - Постійні збої автентифікації одразу пропускають увесь провайдер. + - Вимкнення через білінг зазвичай пропускаються, але основного кандидата все ще можна probe-ити з throttle, щоб відновлення було можливим без перезапуску. + - Основного кандидата можна probe-ити ближче до завершення cooldown, із throttle для кожного провайдера. + - Сусідні резервні моделі того самого провайдера можна спробувати попри cooldown, якщо збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо важливо, коли rate limit прив’язаний до моделі, а сусідня модель усе ще може відновитися негайно. + - Тимчасові cooldown-probe обмежені одним на провайдера за один запуск резервного переходу, щоб один провайдер не затримував резервний перехід між провайдерами. -## Перевизначення сеансу та перемикання моделей у live-сеансі +## Перевизначення сеансу та live-перемикання моделей -Зміни моделей сеансу — це спільний стан. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та узгодження live-сеансу читають або записують частини одного й того самого запису сеансу. +Зміни моделі сеансу — це спільний стан. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та live-узгодження сеансу читають або записують частини одного й того самого запису сеансу. -Це означає, що повторні спроби резервного перемикання мають координуватися з перемиканням моделей у live-сеансі: +Це означає, що повторні спроби резервного переходу мають узгоджуватися з live-перемиканням моделі: - Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`. -- Зміни моделі, ініційовані системою, як-от ротація резервного перемикання, перевизначення Heartbeat або Compaction, ніколи самі по собі не позначають очікуване live-перемикання. -- Перед початком повторної спроби резервного перемикання виконавець відповіді зберігає вибрані поля перевизначення резервного перемикання в записі сеансу. -- На наступному запуску автоматичні перевизначення резервного перемикання очищуються перед вибором моделі, щоб знову спробувати налаштовану основну модель. Якщо вона все ще нездорова, цикл резервного перемикання записує нове автоматичне перевизначення для цієї нової спроби. -- Перевизначення моделей користувача (`modelOverrideSource: "user"`) і застарілі перевизначення без поля джерела залишаються постійними між ходами. -- Узгодження live-сеансу надає перевагу збереженим перевизначенням сеансу над застарілими полями моделі під час виконання. -- Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюжку резервного перемикання, OpenClaw одразу переходить до цієї вибраної моделі замість того, щоб спочатку проходити несуміжних кандидатів. -- Якщо спроба резервного перемикання не вдається, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. +- Зміни моделі, ініційовані системою, як-от ротація резервного переходу, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване live-перемикання. +- Перед початком повторної спроби резервного переходу виконавець відповіді зберігає вибрані поля перевизначення резервного переходу в записі сеансу. +- Автоматичні перевизначення резервного переходу залишаються вибраними в наступних ходах, щоб OpenClaw не probe-ив завідомо погану основну модель у кожному повідомленні. `/new`, `/reset` і `sessions.reset` очищають перевизначення з джерелом auto і повертають сеанс до налаштованого стандартного значення. +- `/status` показує вибрану модель, а коли стан резервного переходу відрізняється — активну резервну модель і причину. +- Live-узгодження сеансу надає перевагу збереженим перевизначенням сеансу над застарілими полями моделі під час виконання. +- Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюжку резервного переходу, OpenClaw одразу переходить до цієї вибраної моделі замість того, щоб спочатку проходити не пов’язаних кандидатів. +- Якщо спроба резервного переходу завершується помилкою, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. Це запобігає класичній гонці: - - Вибрана основна модель завершується невдачею. + + Вибрана основна модель завершується помилкою. - + Резервного кандидата вибрано в пам’яті. Сховище сеансу все ще відображає стару основну модель. - Узгодження live-сеансу читає застарілий стан сеансу. + Live-узгодження сеансу читає застарілий стан сеансу. - Повторну спробу повертає назад до старої моделі ще до початку спроби резервного перемикання. + Повторну спробу повертає назад до старої моделі ще до початку спроби резервного переходу. -Збережене перевизначення резервного перемикання закриває це вікно, а вузьке відкочування зберігає недоторканими новіші ручні або виконувані під час роботи зміни сеансу. +Збережене перевизначення резервного переходу закриває це вікно, а вузьке відкочування зберігає недоторканими новіші ручні або runtime-зміни сеансу. ## Спостережуваність і зведення збоїв -`runWithModelFallback(...)` записує деталі кожної спроби, які використовуються в журналах і повідомленнях для користувача про періоди охолодження: +`runWithModelFallback(...)` записує деталі по кожній спробі, які використовуються в логах і в повідомленнях для користувача про cooldown: -- спробуваний provider/model -- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного перемикання) +- спробувані provider/model +- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного переходу) - необов’язковий status/code - зрозуміле людині зведення помилки -Коли всі кандидати завершуються невдачею, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати точніше повідомлення, наприклад «усі моделі тимчасово обмежені лімітами швидкості», і включити найближчий час завершення охолодження, якщо він відомий. +Коли всі кандидати завершуються помилкою, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати точніше повідомлення, наприклад «усі моделі тимчасово обмежені через rate limit», і додати найближчий час завершення cooldown, якщо він відомий. -Це зведення охолодження враховує модель: +Це зведення cooldown враховує модель: -- несуміжні ліміти швидкості, прив’язані до моделі, ігноруються для ланцюжка спробуваних provider/model -- якщо блокування, що залишилося, є відповідним лімітом швидкості, прив’язаним до моделі, OpenClaw повідомляє про останній відповідний час завершення, який і далі блокує цю модель +- не пов’язані rate limit із прив’язкою до моделі ігноруються для ланцюжка спробуваних provider/model +- якщо блокування, що лишилося, є відповідним rate limit із прив’язкою до моделі, OpenClaw повідомляє останній відповідний час завершення, який і далі блокує цю модель ## Пов’язана конфігурація @@ -327,4 +328,4 @@ OpenClaw будує список кандидатів із поточно зап - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` - маршрутизації `agents.defaults.imageModel` -Див. [Моделі](/uk/concepts/models), щоб ознайомитися з ширшим оглядом вибору моделей і резервного перемикання. +Див. [Моделі](/uk/concepts/models), щоб ознайомитися з ширшим оглядом вибору моделей і резервного переходу. diff --git a/docs/uk/gateway/local-models.md b/docs/uk/gateway/local-models.md index ea704d80a..d94ea8f8c 100644 --- a/docs/uk/gateway/local-models.md +++ b/docs/uk/gateway/local-models.md @@ -1,22 +1,22 @@ --- read_when: - - Ви хочете розгортати моделі зі свого GPU-сервера + - Ви хочете обслуговувати моделі з власного сервера з GPU - Ви налаштовуєте LM Studio або OpenAI-сумісний проксі - Вам потрібні найбезпечніші рекомендації щодо локальних моделей summary: Запуск OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні кінцеві точки OpenAI) title: Локальні моделі x-i18n: - generated_at: "2026-04-27T08:18:08Z" + generated_at: "2026-04-27T08:31:12Z" model: gpt-5.4 provider: openai - source_hash: d6d44f451e14e74f49b8fb23c7c890c8a13a76c56ef82e5d271cfbb7d90f7c81 + source_hash: 0e2733bd1d6f9e57f0b0fb888d28beebff321d12684a6ea670bee327d2ced8dc source_path: gateway/local-models.md workflow: 15 --- -Локальний запуск можливий, але OpenClaw очікує великий контекст + сильний захист від prompt injection. Малі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 Mac Studio у максимальній конфігурації або еквівалентний GPU-риг (~$30k+)**. Один GPU на **24 ГБ** підходить лише для легших запитів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик prompt injection (див. [Безпека](/uk/gateway/security)). +Локальний запуск можливий, але OpenClaw очікує великий контекст і надійний захист від інʼєкцій у промпти. Невеликі відеокарти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 повністю укомплектовані Mac Studio або еквівалентна GPU-система (~$30k+)**. Одна GPU на **24 GB** підходить лише для простіших запитів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик інʼєкцій у промпти (див. [Безпека](/uk/gateway/security)). -Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — рекомендаційний посібник для потужніших локальних стеків і власних локальних серверів, сумісних з OpenAI. +Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — рекомендаційний посібник для локальних стеків вищого класу та власних локальних серверів, сумісних з OpenAI. ## Рекомендовано: LM Studio + велика локальна модель (Responses API) @@ -60,15 +60,15 @@ x-i18n: **Контрольний список налаштування** - Встановіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small” / сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` показує її. -- Замініть `my-local-model` на фактичний ID моделі, показаний у LM Studio. +- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small” і сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` її показує. +- Замініть `my-local-model` на фактичний ідентифікатор моделі, показаний у LM Studio. - Тримайте модель завантаженою; холодне завантаження додає затримку запуску. -- За потреби змініть `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється. +- Скоригуйте `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється. - Для WhatsApp дотримуйтеся Responses API, щоб надсилався лише фінальний текст. -Тримайте розміщені моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб резервні варіанти залишалися доступними. +Залишайте хостингові моделі налаштованими навіть під час локальної роботи; використовуйте `models.mode: "merge"`, щоб запасні варіанти залишалися доступними. -### Гібридна конфігурація: основна розміщена модель, локальна резервна +### Гібридна конфігурація: хостингова основна модель, локальна запасна ```json5 { @@ -109,18 +109,18 @@ x-i18n: } ``` -### Насамперед локально, із резервом у хмарі +### Спочатку локальна модель, із хостинговою страховкою -Поміняйте місцями основну модель і порядок резервних; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було переключитися на Sonnet або Opus, коли локальний сервер недоступний. +Поміняйте місцями основну модель і порядок запасних; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було переключитися на Sonnet або Opus, коли локальний сервер недоступний. ### Регіональний хостинг / маршрутизація даних -- Розміщені варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з кінцевими точками, прив’язаними до регіону (наприклад, розміщеними у США). Виберіть там регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для резервних Anthropic/OpenAI. -- Лише локальний запуск залишається найкращим варіантом для конфіденційності; регіональна маршрутизація для розміщених моделей — проміжний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних. +- Хостингові варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з кінцевими точками, привʼязаними до регіону (наприклад, хостинг у США). Виберіть там регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для запасних варіантів Anthropic/OpenAI. +- Лише локальний режим залишається найсильнішим шляхом для приватності; регіональна маршрутизація хостингових моделей — це компромісний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних. ## Інші локальні проксі, сумісні з OpenAI -vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщо вони надають кінцеву точку `/v1` у стилі OpenAI. Замініть блок provider вище на вашу кінцеву точку та ID моделі: +vLLM, LiteLLM, OAI-proxy або власні шлюзи підходять, якщо вони надають кінцеву точку `/v1` у стилі OpenAI. Замініть блок provider вище на свою кінцеву точку та ідентифікатор моделі: ```json5 { @@ -149,64 +149,37 @@ vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщ } ``` -Зберігайте `models.mode: "merge"`, щоб розміщені моделі залишалися доступними як резервні. -Використовуйте `models.providers..timeoutSeconds` для повільних локальних або віддалених -серверів моделей, перш ніж збільшувати `agents.defaults.timeoutSeconds`. Тайм-аут провайдера -застосовується лише до HTTP-запитів моделі, зокрема до встановлення з’єднання, заголовків, потокової -передачі тіла відповіді та загального переривання guarded-fetch. +Залишайте `models.mode: "merge"`, щоб хостингові моделі були доступні як запасні. +Використовуйте `models.providers..timeoutSeconds` для повільних локальних або віддалених серверів моделей, перш ніж збільшувати `agents.defaults.timeoutSeconds`. Тайм-аут провайдера застосовується лише до HTTP-запитів моделі, включно з підключенням, заголовками, потоковою передачею тіла та загальним guarded-fetch abort. -Примітка щодо поведінки для локальних/проксійованих бекендів `/v1`: +Примітка щодо поведінки локальних/проксійованих бекендів `/v1`: -- OpenClaw розглядає їх як проксі-маршрути, сумісні з OpenAI, а не як нативні - кінцеві точки OpenAI -- тут не застосовується формування запитів лише для нативного OpenAI: немає - `service_tier`, немає Responses `store`, немає формування payload для сумісності - з OpenAI reasoning і немає підказок для кешу prompt -- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`) - не додаються до цих власних URL проксі +- OpenClaw розглядає їх як проксі-маршрути, сумісні з OpenAI, а не як нативні кінцеві точки OpenAI +- тут не застосовується формування запитів, яке працює лише для нативного OpenAI: без `service_tier`, без Responses `store`, без формування payload для сумісності з міркуваннями OpenAI і без підказок кешу промптів +- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`) не додаються до цих власних проксі-URL -Примітки щодо сумісності для суворіших бекендів, сумісних з OpenAI: +Примітки щодо сумісності для суворіших OpenAI-сумісних бекендів: -- Деякі сервери приймають лише рядковий `messages[].content` у Chat Completions, а не - структуровані масиви частин контенту. Для таких кінцевих точок встановіть - `models.providers..models[].compat.requiresStringContent: true`. -- Деякі локальні моделі виводять окремі запити до інструментів у дужках як текст, наприклад - `[tool_name]`, після якого йде JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює - їх на справжні виклики інструментів лише тоді, коли назва точно збігається із зареєстрованим - інструментом для цього ходу; інакше блок розглядається як непідтримуваний текст і - приховується від видимих для користувача відповідей. -- Якщо модель виводить JSON, XML або текст у стилі ReAct, що виглядає як виклик - інструмента, але провайдер не передав структурований виклик, OpenClaw залишає це - як текст і записує попередження з run id, провайдером/моделлю, виявленим шаблоном і - назвою інструмента, якщо вона доступна. Розцінюйте це як несумісність - викликів інструментів на рівні провайдера/моделі, а не як завершений запуск інструмента. -- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною - формою prompt середовища виконання агента OpenClaw, особливо коли включені схеми інструментів. Якщо - бекенд працює для маленьких прямих викликів `/v1/chat/completions`, але не працює у звичайних - ходах агента OpenClaw, спочатку спробуйте - `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі - стандартні інструменти, як-от `browser`, `cron` і `message`; це експериментальний - прапорець, а не стабільне налаштування режиму за замовчуванням. Див. - [Експериментальні можливості](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте - `models.providers..models[].compat.supportsTools: false`. -- Якщо бекенд і далі не працює лише на більших запусках OpenClaw, то проблема, як правило, - полягає у можливостях моделі/сервера на стороні постачальника або у багу бекенда, а не в транспортному шарі OpenClaw. +- Деякі сервери приймають лише рядковий `messages[].content` у Chat Completions, а не структуровані масиви частин вмісту. Для таких кінцевих точок установіть `models.providers..models[].compat.requiresStringContent: true`. +- Деякі локальні моделі виводять окремі запити інструментів у дужках як текст, наприклад `[tool_name]`, потім JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює їх на реальні виклики інструментів лише тоді, коли назва точно збігається із зареєстрованим інструментом для цього ходу; інакше блок вважається непідтримуваним текстом і приховується від видимих користувачу відповідей. +- Якщо модель виводить JSON, XML або текст у стилі ReAct, що виглядає як виклик інструмента, але провайдер не повернув структурований виклик, OpenClaw залишає це як текст і записує попередження з ідентифікатором запуску, провайдером/моделлю, виявленим шаблоном і назвою інструмента, якщо вона доступна. Розглядайте це як несумісність викликів інструментів у провайдера/моделі, а не як завершене виконання інструмента. +- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною формою промпта середовища агента OpenClaw, особливо коли включені схеми інструментів. Якщо бекенд працює для маленьких прямих викликів `/v1/chat/completions`, але не працює для звичайних ходів агента OpenClaw, спочатку спробуйте `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі інструменти за замовчуванням, такі як `browser`, `cron` і `message`; це експериментальний прапорець, а не стабільний параметр стандартного режиму. Див. [Експериментальні можливості](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте `models.providers..models[].compat.supportsTools: false`. +- Якщо бекенд і далі не працює лише на більших запусках OpenClaw, то решта проблеми зазвичай повʼязана з обмеженнями моделі/сервера на боці upstream або з помилкою бекенда, а не з транспортним рівнем OpenClaw. -## Усунення проблем +## Усунення несправностей -- Gateway може під’єднатися до проксі? `curl http://127.0.0.1:1234/v1/models`. -- Модель у LM Studio вивантажена? Завантажте її знову; холодний старт — часта причина “зависання”. -- OpenClaw попереджає, коли виявлене вікно контексту менше за **32k**, і блокує роботу нижче **16k**. Якщо ви натрапили на цю попередню перевірку, збільшіть ліміт контексту сервера/моделі або виберіть більшу модель. -- Помилки контексту? Зменште `contextWindow` або підвищте ліміт сервера. -- Сервер, сумісний з OpenAI, повертає `messages[].content ... expected a string`? +- Gateway може дістатися до проксі? `curl http://127.0.0.1:1234/v1/models`. +- Модель LM Studio вивантажена? Завантажте знову; холодний старт — поширена причина “зависання”. +- Локальний сервер повідомляє `terminated`, `ECONNRESET` або закриває потік посеред ходу? + OpenClaw записує низькокардинальний `model.call.error.failureKind`, а також знімок RSS/heap процесу OpenClaw у діагностику. Для тиску на памʼять у LM Studio/Ollama зіставте цей час із журналом сервера або журналом аварій macOS / jetsam, щоб підтвердити, чи було вбито сервер моделі. +- OpenClaw попереджає, коли виявлене вікно контексту нижче за **32k**, і блокує, якщо нижче за **16k**. Якщо ви натрапили на цю попередню перевірку, збільште ліміт контексту сервера/моделі або виберіть більшу модель. +- Помилки контексту? Зменште `contextWindow` або збільште ліміт вашого сервера. +- OpenAI-сумісний сервер повертає `messages[].content ... expected a string`? Додайте `compat.requiresStringContent: true` у запис цієї моделі. -- Маленькі прямі виклики `/v1/chat/completions` працюють, але `openclaw infer model run` - не працює з Gemma або іншою локальною моделлю? Спочатку вимкніть схеми інструментів через - `compat.supportsTools: false`, а потім повторіть перевірку. Якщо сервер і далі падає лише - на більших prompt OpenClaw, розцінюйте це як обмеження сервера/моделі на стороні постачальника. -- Безпека: локальні моделі оминають фільтри на стороні провайдера; тримайте агентів вузькоспеціалізованими, а Compaction увімкненим, щоб обмежити радіус ураження від prompt injection. +- Прямі маленькі виклики `/v1/chat/completions` працюють, але `openclaw infer model run` не працює на Gemma або іншій локальній моделі? Спочатку вимкніть схеми інструментів через `compat.supportsTools: false`, а потім перевірте ще раз. Якщо сервер і далі аварійно завершується лише на більших промптах OpenClaw, розглядайте це як обмеження моделі/сервера на боці upstream. +- Безпека: локальні моделі обходяться без фільтрів на боці провайдера; звужуйте агентів і тримайте увімкненим Compaction, щоб обмежити радіус ураження від інʼєкцій у промпти. -## Пов’язане +## Повʼязане - [Довідник з конфігурації](/uk/gateway/configuration-reference) -- [Перемикання на резервну модель](/uk/concepts/model-failover) +- [Резервне перемикання моделей](/uk/concepts/model-failover) diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md index f9ad3a9f5..0e06e4dfb 100644 --- a/docs/uk/gateway/opentelemetry.md +++ b/docs/uk/gateway/opentelemetry.md @@ -1,38 +1,38 @@ --- read_when: - Ви хочете надсилати дані про використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry - - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого бекенда OTLP - - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення + - Ви налаштовуєте traces, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда + - Вам потрібні точні назви метрик, spans або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP) -title: експорт OpenTelemetry +title: Експорт OpenTelemetry x-i18n: - generated_at: "2026-04-26T21:17:06Z" + generated_at: "2026-04-27T08:31:11Z" model: gpt-5.4 provider: openai - source_hash: 1ad923fff12ff89766999370fe39a75c1aa5f386ce4641fde1c385b24439cc1b + source_hash: e9d06589d281223ebb57e76f6f19441d30c138b9f7b0636198ab7bae5fad3c8a source_path: gateway/opentelemetry.md workflow: 15 --- OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel` -з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, -працює без змін у коді. Для локальних файлових журналів і того, як їх читати, див. +за допомогою **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, +працює без змін у коді. Для локальних файлових журналів і способів їх читання див. [Журналювання](/uk/logging). ## Як це працює разом -- **Діагностичні події** — це структуровані внутрішньопроцесні записи, які створюються - Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг +- **Події діагностики** — це структуровані внутрішньопроцесні записи, які видають + Gateway і вбудовані plugins для запусків моделей, потоку повідомлень, сесій, черг та exec. -- **Plugin `diagnostics-otel`** підписується на ці події й експортує їх як - OpenTelemetry **метрики**, **трасування** та **журнали** через OTLP/HTTP. -- **Виклики провайдера** отримують заголовок W3C `traceparent` із контексту - довіреного span виклику моделі OpenClaw, якщо транспорт провайдера приймає власні - заголовки. Контекст трасування, створений Plugin, не передається далі. -- Експортери підключаються лише тоді, коли увімкнено і поверхню діагностики, і Plugin, - тому внутрішньопроцесна вартість за замовчуванням залишається майже нульовою. +- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як + OpenTelemetry **метрики**, **traces** і **журнали** через OTLP/HTTP. +- **Виклики провайдера** отримують заголовок W3C `traceparent` із довіреного + контексту span виклику моделі OpenClaw, якщо транспорт провайдера приймає + користувацькі заголовки. Контекст trace, який видає Plugin, не поширюється. +- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і plugin, + тому внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. -## Швидкий старт +## Швидкий початок ```json5 { @@ -59,7 +59,7 @@ OpenClaw експортує діагностику через вбудовани } ``` -Ви також можете увімкнути Plugin з CLI: +Ви також можете ввімкнути plugin з CLI: ```bash openclaw plugins enable diagnostics-otel @@ -71,13 +71,13 @@ openclaw plugins enable diagnostics-otel ## Експортовані сигнали -| Сигнал | Що до нього входить | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску пам’яті. | -| **Трасування** | Спани для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | -| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | +| Signal | Що в нього входить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| **Metrics** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску пам’яті. | +| **Traces** | Spans для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Logs** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | -Перемикайте `traces`, `metrics` і `logs` незалежно. За замовчуванням усі три +Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням увімкнені, коли `diagnostics.otel.enabled` має значення true. ## Довідник конфігурації @@ -99,7 +99,7 @@ openclaw plugins enable diagnostics-otel metrics: true, logs: true, sampleRate: 0.2, // root-span sampler, 0.0..1.0 - flushIntervalMs: 60000, // metric export interval (min 1000ms) + flushIntervalMs: 60000, // interval exportu метрик (мінімум 1000ms) captureContent: { enabled: false, inputMessages: false, @@ -115,68 +115,68 @@ openclaw plugins enable diagnostics-otel ### Змінні середовища -| Змінна | Призначення | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для конкретних сигналів, які використовуються, коли не задано відповідний ключ конфігурації `diagnostics.otel.*Endpoint`. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою. | -| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб виводити останній експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | -| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інше preload-рішення або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | +| Variable | Призначення | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для окремих сигналів, що використовуються, коли не задано відповідний ключ конфігурації `diagnostics.otel.*Endpoint`. Конфігурація для конкретного сигналу має пріоритет над env для конкретного сигналу, яке має пріоритет над спільною кінцевою точкою. | +| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб видавати найновіший експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інший preload або host process уже зареєстрував глобальний SDK OpenTelemetry. Тоді plugin пропустить власний життєвий цикл NodeSDK, але все одно підключить слухачі діагностики та врахує `traces`/`metrics`/`logs`. | ## Конфіденційність і захоплення вмісту -Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять -обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані request id) -і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані -інструментів або ключі сесій. +Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Spans містять +обмежені ідентифікатори (канал, провайдер, модель, категорію помилки, ідентифікатори запитів +лише у вигляді хешів) і ніколи не включають текст prompt, текст відповіді, вхідні дані +інструментів, вихідні дані інструментів або ключі сесії. Вихідні запити до моделі можуть містити заголовок W3C `traceparent`. Цей заголовок -генерується лише з діагностичного контексту трасування, що належить OpenClaw, для активного виклику -моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому Plugins або -власні параметри провайдера не можуть підробити походження трасування між сервісами. +генерується лише з контексту trace діагностики, що належить OpenClaw, для активного +виклику моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому plugins або +користувацькі параметри провайдера не можуть підробити походження cross-service trace. -Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш колектор і -політика зберігання схвалені для тексту промптів, відповідей, інструментів або системних промптів. -Кожен підключ окремо вмикається явно: +Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш колектор +і політика зберігання схвалені для тексту prompt, відповіді, інструментів або system prompt. +Кожен вкладений ключ вмикається окремо: -- `inputMessages` — вміст користувацького промпту. +- `inputMessages` — вміст prompt користувача. - `outputMessages` — вміст відповіді моделі. -- `toolInputs` — корисні навантаження аргументів інструментів. -- `toolOutputs` — корисні навантаження результатів інструментів. -- `systemPrompt` — зібраний системний/розробницький промпт. +- `toolInputs` — payload аргументів інструментів. +- `toolOutputs` — payload результатів інструментів. +- `systemPrompt` — зібраний system/developer prompt. -Коли ввімкнено будь-який підключ, спани моделі та інструментів отримують обмежені, відредаговані -атрибути `openclaw.content.*` лише для цього класу. +Коли ввімкнено будь-який вкладений ключ, spans моделей та інструментів отримують обмежені, +відредаговані атрибути `openclaw.content.*` лише для цього класу. ## Семплювання та скидання -- **Трасування:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає все, - `1.0` зберігає все). -- **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). -- **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). Вони використовують - шлях редагування діагностичних log record, а не форматування консолі. Для інсталяцій із великим - обсягом даних краще використовувати семплювання/фільтрацію в колекторі OTLP, а не локальне семплювання. -- **Кореляція файлових журналів:** журнали JSONL включають верхньорівневі `traceId`, - `spanId`, `parentSpanId` і `traceFlags`, коли виклик журналювання містить коректний - діагностичний контекст трасування, що дає змогу обробникам журналів поєднувати локальні рядки журналу - з експортованими спанами. +- **Traces:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає всі, + `1.0` зберігає всі). +- **Metrics:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). +- **Logs:** OTLP logs враховують `logging.level` (рівень файлового журналу). Вони використовують + шлях редагування діагностичних log record, а не форматування консолі. Для інсталяцій із + великим обсягом даних слід надавати перевагу семплюванню/фільтрації в колекторі OTLP, а не локальному семплюванню. +- **Кореляція файлових журналів:** JSONL-файли журналів містять верхньорівневі `traceId`, + `spanId`, `parentSpanId` і `traceFlags`, коли виклик журналу несе чинний діагностичний + контекст trace, що дозволяє процесорам журналів поєднувати локальні рядки журналу з + експортованими spans. - **Кореляція запитів:** HTTP-запити Gateway і кадри WebSocket створюють внутрішню - область трасування запиту. Журнали та діагностичні події в цій області за замовчуванням - успадковують трасування запиту, тоді як спани запуску агента та виклику моделі - створюються як дочірні, щоб заголовки провайдера `traceparent` залишалися в межах того самого трасування. + область trace запиту. Журнали й події діагностики в цій області за замовчуванням + успадковують trace запиту, тоді як spans запуску агента та виклику моделі + створюються як дочірні, щоб заголовки провайдера `traceparent` залишалися в межах того самого trace. ## Експортовані метрики -### Використання моделей +### Використання моделі - `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`) - `openclaw.cost.usd` (лічильник, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.run.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.context.tokens` (гістограма, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (гістограма, метрика семантичних конвенцій GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних конвенцій GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) -- `openclaw.model_call.duration_ms` (гістограма, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`) +- `gen_ai.client.token.usage` (гістограма, метрика семантичних угод GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних угод GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`) +- `openclaw.model_call.duration_ms` (гістограма, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, а також `openclaw.errorCategory` і `openclaw.failureKind` для класифікованих помилок) - `openclaw.model_call.request_bytes` (гістограма, розмір у байтах UTF-8 фінального payload запиту до моделі; без необробленого вмісту payload) - `openclaw.model_call.response_bytes` (гістограма, розмір у байтах UTF-8 потокових подій відповіді моделі; без необробленого вмісту відповіді) - `openclaw.model_call.time_to_first_byte_ms` (гістограма, час до першої потокової події відповіді) @@ -203,9 +203,9 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck_age_ms` (гістограма, attrs: `openclaw.state`) - `openclaw.run.attempt` (лічильник, attrs: `openclaw.attempt`) -### Життєвий цикл harness +### Життєвий цикл Harness -- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` для помилок) +- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` у разі помилок) ### Exec @@ -219,23 +219,24 @@ openclaw plugins enable diagnostics-otel - `openclaw.tool.loop.iterations` (лічильник, attrs: `openclaw.toolName`, `openclaw.outcome`) - `openclaw.tool.loop.duration_ms` (гістограма, attrs: `openclaw.toolName`, `openclaw.outcome`) -## Експортовані спани +## Експортовані spans - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) - - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні конвенції GenAI + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` - `openclaw.run` - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory` - `openclaw.model.call` - - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні конвенції GenAI + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` + - `openclaw.errorCategory` і необов’язковий `openclaw.failureKind` у разі помилок - `openclaw.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms` - - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для upstream request id провайдера; сирі id не експортуються) + - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для upstream request id провайдера; необроблені id не експортуються) - `openclaw.harness.run` - `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.provider`, `openclaw.model`, `openclaw.channel` - - Під час завершення: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active` + - Після завершення: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active` - У разі помилки: `openclaw.harness.phase`, `openclaw.errorCategory`, необов’язковий `openclaw.harness.cleanup_failed` - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` @@ -252,27 +253,27 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту промпту, історії, відповіді або ключа сесії) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, history, response або session key) - `openclaw.tool.loop` - - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, params або виводу інструмента) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` -Коли захоплення вмісту явно ввімкнене, спани моделі та інструментів також можуть +Якщо захоплення вмісту явно ввімкнено, spans моделей та інструментів також можуть включати обмежені, відредаговані атрибути `openclaw.content.*` для конкретних -класів вмісту, на які ви дали згоду. +класів вмісту, які ви ввімкнули. -## Каталог діагностичних подій +## Каталог подій діагностики -Наведені нижче події лежать в основі метрик і спанів вище. Plugins також можуть -підписуватися на них безпосередньо без експорту OTLP. +Наведені нижче події є основою для метрик і spans вище. Plugins також можуть підписуватися +на них напряму без експорту OTLP. -**Використання моделей** +**Використання моделі** - `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, - id сесій. `usage` — це облік провайдера/ходу для вартості й телеметрії; - `context.used` — це поточний знімок промпту/контексту і він може бути меншим за - `usage.total` провайдера, коли задіяно кешоване введення або виклики циклу інструментів. + id сесії. `usage` — це облік провайдера/ходу для вартості й телеметрії; + `context.used` — це поточний знімок prompt/контексту, який може бути меншим за + `usage.total` провайдера, коли задіяно кешований ввід або виклики циклу інструментів. **Потік повідомлень** @@ -285,15 +286,15 @@ openclaw plugins enable diagnostics-otel - `queue.lane.enqueue` / `queue.lane.dequeue` - `session.state` / `session.stuck` - `run.attempt` -- `diagnostic.heartbeat` (агреговані лічильники: webhook/черга/сесія) +- `diagnostic.heartbeat` (агреговані лічильники: webhooks/queue/session) -**Життєвий цикл harness** +**Життєвий цикл Harness** - `harness.run.started` / `harness.run.completed` / `harness.run.error` — - життєвий цикл кожного запуску для harness агента. Включає `harnessId`, необов’язковий - `pluginId`, провайдер/модель/канал і id запуску. Завершення додає + життєвий цикл agent harness для кожного запуску. Включає `harnessId`, необов’язковий + `pluginId`, провайдера/модель/канал і id запуску. Завершення додає `durationMs`, `outcome`, необов’язкові `resultClassification`, `yieldDetected` - і лічильники `itemLifecycle`. Помилки додають `phase` + та лічильники `itemLifecycle`. Помилки додають `phase` (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` і необов’язковий `cleanupFailed`. @@ -305,7 +306,7 @@ openclaw plugins enable diagnostics-otel ## Без експортера -Ви можете залишити діагностичні події доступними для Plugins або власних приймачів без +Ви можете залишити події діагностики доступними для plugins або користувацьких sinks без запуску `diagnostics-otel`: ```json5 @@ -314,8 +315,8 @@ openclaw plugins enable diagnostics-otel } ``` -Для цільового виводу налагодження без підвищення `logging.level` використовуйте -прапорці діагностики. Прапорці нечутливі до регістру й підтримують шаблони (наприклад, `telegram.*` або +Для цільового налагоджувального виводу без підвищення `logging.level` використовуйте +прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-вирази (наприклад, `telegram.*` або `*`): ```json5 @@ -324,13 +325,13 @@ openclaw plugins enable diagnostics-otel } ``` -Або як одноразове перевизначення через змінну середовища: +Або як одноразове перевизначення через env: ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще +Вивід прапорців надходить до стандартного файла журналу (`logging.file`) і все ще редагується через `logging.redactSensitive`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). @@ -347,8 +348,8 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ## Пов’язане -- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, перегляд через CLI та вкладка Журнали в Control UI -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Прапорці діагностики](/uk/diagnostics/flags) — прапорці цільового журналювання для налагодження -- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент підтримки для збору пакета даних оператора (окремо від експорту OTEL) +- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, tailing у CLI та вкладка Logs у Control UI +- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналів налагодження +- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент operator support bundle (окремо від експорту OTEL) - [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index ef97be4a3..d4fa0920e 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,65 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Маніфест Plugin + вимоги до схеми JSON (сувора валідація конфігурації) + - Ви створюєте plugin для OpenClaw + - Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin +summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-27T08:08:31Z" + generated_at: "2026-04-27T08:31:09Z" model: gpt-5.4 provider: openai - source_hash: 9d6e1da1cc57f6ba89ef511b01636439dd34f0b847a306b96271ccf9c2b878d4 + source_hash: 5b3ffcdfcf09b4480d0cec007d645daebdaeb86a051a233dec192f555359162a source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту plugin OpenClaw**. -Для сумісних макетів пакетів див. [Пакети Plugin](/uk/plugins/bundles). +Сумісні макети bundle описано тут: [Пакети Plugin](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати bundle використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять -валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію +за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета разом з оголошеними -коренями Skills, коренями команд Claude, типовими значеннями `settings.json` для пакетів Claude, -типовими значеннями LSP для пакетів Claude та підтримуваними наборами хуків, коли макет відповідає -очікуванням runtime OpenClaw. +Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними +коренями skill, коренями команд Claude, типовими значеннями `settings.json` у bundle Claude, +типовими значеннями LSP у bundle Claude та підтримуваними наборами hook, якщо макет відповідає +очікуванням середовища виконання OpenClaw. -Кожен нативний Plugin OpenClaw **обов’язково** має містити файл `openclaw.plugin.json` у -**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються -помилками Plugin і блокують валідацію конфігурації. +Кожен власний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у +**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду plugin**. Відсутні або недійсні маніфести розглядаються як +помилки plugin і блокують валідацію конфігурації. -Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). -Щодо нативної моделі можливостей і актуальних рекомендацій із зовнішньої сумісності: +Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin). +Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає **перед завантаженням коду -вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску -runtime Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду +вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску +середовища виконання plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих auth, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища provider, варіанти auth) - підказок активації для поверхонь control-plane - скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти -- метаданих конфігурації для конкретних каналів, об’єднаних у каталог і поверхні валідації +- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- метаданих конфігурації, специфічних для каналу, що об’єднуються в каталог і поверхні валідації -**Не використовуйте його для:** реєстрації поведінки runtime, оголошення -точок входу коду або метаданих встановлення npm. Це належить коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення +точок входу коду або метаданих встановлення npm. Для цього призначені код вашого plugin +і `package.json`. ## Мінімальний приклад @@ -79,7 +80,7 @@ runtime Plugin. { "id": "openrouter", "name": "OpenRouter", - "description": "Плагін провайдера OpenRouter", + "description": "Плагін provider OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -140,70 +141,72 @@ runtime Plugin. | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного runtime Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту і використовуються для автозавантаження Plugin до запуску runtime. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього читання списків, онбордингу, вибору моделей, псевдонімів і приховування без завантаження runtime Plugin. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких слід перевіряти синтетичний хук автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або стан облікових даних середовища. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це впродовж періоду зворотної сумісності. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, що спільно використовує базовий ключ API провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для каналів, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого підключення прапорців CLI. | -| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, ініційованого провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактична поведінка все ще належить runtime Plugin. | -| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin. | -| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, що використовуються спільним хостом `openclaw qa` до завантаження runtime Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту й об’єднуються з поверхнями виявлення та валідації до завантаження runtime. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий опис, який показується на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки про чутливість для полів конфігурації. | +| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON schema для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає bundle plugin як увімкнений типово. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався типово вимкненим. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори channel, якими володіє цей plugin. Використовуються для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори provider, якими володіє цей plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення provider, відносний до кореня plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання plugin. | +| `modelSupport` | Ні | `object` | Метадані скороченого запису для сімейств моделей, якими володіє маніфест, що використовуються для автозавантаження plugin до запуску середовища виконання. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для provider, якими володіє цей plugin. Це контракт control-plane для майбутнього читання списків у режимі лише для читання, онбордингу, вибору моделей, аліасів і приховування без завантаження середовища виконання plugin. | +| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, якою володіє provider. Використовуйте її, щоб виключити локальні/self-hosted provider із віддалених каталогів цін або зіставити посилання provider з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів provider у core. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів provider, які core має класифікувати до завантаження середовища виконання provider. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend виведення CLI, якими володіє цей plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевірити синтетичний hook auth, яким володіє plugin, під час холодного виявлення моделей до завантаження середовища виконання. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, якими володіє bundle plugin, що представляють не секретний локальний стан, OAuth або стан облікових даних середовища. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin, що мають створювати обізнану про plugin конфігурацію та діагностику CLI до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку auth/статусу provider. Для нових plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час вікна знецінення. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку auth, наприклад provider для кодування, який спільно використовує базовий ключ API provider та профілі auth. | +| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel на основі env або поверхонь auth, які мають бачити загальні допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів auth для селекторів онбордингу, визначення бажаного provider і простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, яке запускається provider, командою, channel, маршрутом і можливістю. Лише метадані; фактичною поведінкою, як і раніше, володіє середовище виконання plugin. | +| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | +| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання plugin. | +| `contracts` | Ні | `object` | Статичний знімок bundle можливостей для зовнішніх hook auth, speech, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw читає це до завантаження runtime провайдера. -Списки налаштування провайдера використовують ці варіанти маніфесту, варіанти -налаштування, отримані з дескриптора, і метадані каталогу встановлення без -завантаження runtime провайдера. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth. +OpenClaw читає це до завантаження середовища виконання provider. +Списки налаштування provider використовують ці варіанти маніфесту, варіанти +налаштування, похідні від дескрипторів, і метадані каталогу встановлення без +завантаження середовища виконання provider. -| Поле | Обов’язкове | Тип | Що воно означає | -| -------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| `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` | Ідентифікатор provider, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу auth, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта auth, який використовується в онбордингу та потоках CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних селекторах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків auth з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має відображатися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть -помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду runtime Plugin. +Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища +виконання, яку користувачі можуть помилково вказати в `plugins.allow` або +спробувати запустити як кореневу команду CLI. OpenClaw використовує ці +метадані для діагностики без імпорту коду середовища виконання plugin. ```json { @@ -217,37 +220,41 @@ OpenClaw читає це до завантаження runtime провайде } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як команду чату зі слешем, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо така існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | +| `name` | Так | `string` | Назва команди, що належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane -мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли plugin може дешево оголосити, які події +control-plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку runtime, не замінює `register(...)` і не гарантує, що код -Plugin уже виконався. Планувальник активації використовує ці поля для -звуження кола кандидатів Plugin перед переходом до наявних метаданих володіння в маніфесті, -таких як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не +реєструє поведінку середовища виконання, не замінює `register(...)` і не +гарантує, що код plugin уже виконувався. Планувальник активації використовує +ці поля, щоб звузити коло кандидатів plugin, перш ніж переходити до наявних +метаданих володіння маніфестом, таких як `providers`, `channels`, +`commandAliases`, `setup.providers`, `contracts.tools` і hooks. -Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових -підказок планувальнику, які не можна подати через ці поля володіння. -Для псевдонімів runtime CLI, таких як `claude-cli`, -`codex-cli` або `google-gemini-cli`, використовуйте `cliBackends` верхнього рівня; `activation.onAgentHarnesses` призначене лише для -вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. +Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або +`contracts`, коли ці поля виражають відповідний зв’язок. Використовуйте +`activation` для додаткових підказок планувальнику, які не можна подати через +ці поля володіння. +Використовуйте верхньорівневий `cliBackends` для аліасів середовища виконання +CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; +`activation.onAgentHarnesses` призначений лише для вбудованих ідентифікаторів +agent harness, які ще не мають поля володіння. -Цей блок — лише метадані. Він не реєструє поведінку runtime і не -замінює `register(...)`, `setupEntry` чи інші точки входу runtime/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож -відсутні метадані активації зазвичай впливають лише на продуктивність; -це не має змінювати коректність, доки ще існують застарілі резервні варіанти володіння маніфестом. +Цей блок містить лише метадані. Він не реєструє поведінку середовища +виконання і не замінює `register(...)`, `setupEntry` або інші точки входу +середовища виконання/plugin. Поточні споживачі використовують його як підказку +для звуження кола перед ширшим завантаженням plugin, тому відсутність +метаданих активації зазвичай лише впливає на продуктивність; це не повинно +змінювати коректність, доки ще існують застарілі резервні механізми володіння +маніфестом. ```json { @@ -261,61 +268,64 @@ Plugin уже виконався. Планувальник активації в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих harness агента, які мають включати цей Plugin до планів активації/завантаження. Для псевдонімів backend CLI використовуйте `cliBackends` верхнього рівня. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control-plane. За можливості віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають включати цей plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Для аліасів backend CLI використовуйте верхньорівневий `cliBackends`. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають включати цей plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control-plane. За можливості надавайте перевагу вужчим полям. | Поточні активні споживачі: -- планування CLI, ініційоване командою, повертається до застарілих +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску runtime агента використовує `activation.onAgentHarnesses` для - вбудованих harness і `cliBackends[]` верхнього рівня для псевдонімів runtime CLI -- планування setup/каналів, ініційоване каналом, повертається до застарілого володіння `channels[]`, - якщо явні метадані активації каналу відсутні -- планування setup/runtime, ініційоване провайдером, повертається до застарілого - володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані - активації провайдера відсутні +- планування запуску середовища виконання agent використовує + `activation.onAgentHarnesses` для вбудованих harness і верхньорівневий + `cliBackends[]` для аліасів середовища виконання CLI +- планування setup/channel, що запускається channel, повертається до + застарілого володіння `channels[]`, коли явні метадані активації channel + відсутні +- планування setup/runtime, що запускається provider, повертається до + застарілого володіння `providers[]` і верхньорівневого `cliBackends[]`, коли + явні метадані активації provider відсутні -Діагностика планувальника може розрізняти явні підказки активації та резервне -володіння з маніфесту. Наприклад, `activation-command-hint` означає, що -збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, -які найкраще описують володіння. +Діагностика планувальника може розрізняти явні підказки активації та резервний +механізм володіння маніфестом. Наприклад, `activation-command-hint` означає, +що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, +що планувальник натомість використав володіння `commandAliases`. Ці мітки +причин призначені для діагностики хоста та тестів; авторам plugin слід і надалі +оголошувати метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під -спільним коренем `openclaw qa`. Тримайте ці метадані легковаговими й статичними; фактичною -реєстрацією CLI все ще керує runtime Plugin через легковагову -поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner +під спільним коренем `openclaw qa`. Зберігайте ці метадані простими й +статичними; фактичною реєстрацією CLI, як і раніше, володіє середовище +виконання plugin через легковагову поверхню `runtime-api.ts`, яка експортує +`qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Запустити live QA lane Matrix на базі Docker проти одноразового homeserver" + "description": "Запускає lane live QA для Matrix на базі Docker на одноразовому homeserver" } ] } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, -що належать Plugin, до завантаження runtime. +Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві +метадані plugin, якими він володіє, до завантаження середовища виконання. ```json { @@ -334,65 +344,71 @@ Plugin уже виконався. Планувальник активації в } ``` -`cliBackends` верхнього рівня залишається валідним і далі описує -backend CLI inference. `setup.cliBackends` — це поверхня дескриптора, специфічна для setup, -для потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається чинним і надалі описує backend +виведення CLI. `setup.cliBackends` — це поверхня дескриптора, специфічна для +setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -Коли вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною -поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. Якщо дескриптор лише -звужує кандидат Plugin, а setup усе ще потребує багатших runtime-хуків часу налаштування, -встановіть `requiresRuntime: true` і залиште `setup-api` як -резервний шлях виконання. +Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною +поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. +Якщо дескриптор лише звужує коло кандидатів plugin, а setup все ще потребує +багатших hook середовища виконання на час setup, установіть +`requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та -env-змінних. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності -протягом періоду зворотної сумісності, але невбудовані Plugin, які досі його використовують, -отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу -в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` у загальні механізми пошуку +auth provider і змінних середовища. `providerAuthEnvVars` залишається +підтримуваним через адаптер сумісності протягом вікна знецінення, але +неbundle plugin, які все ще його використовують, отримують діагностику +маніфесту. Нові plugin мають розміщувати метадані env для setup/статусу в +`setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, -коли запис setup недоступний або коли `setup.requiresRuntime: false` -оголошує runtime setup непотрібним. Явні записи `providerAuthChoices` залишаються -пріоритетними для власних міток, прапорців CLI, області онбордингу та метаданих асистента. +OpenClaw також може виводити прості варіанти setup із +`setup.providers[].authMethods`, коли запис setup відсутній або коли +`setup.requiresRuntime: false` оголошує, що середовище виконання setup не +потрібне. Явні записи `providerAuthChoices` усе ще мають перевагу для власних +міток, прапорців CLI, області онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw розглядає явне `false` як контракт лише на рівні дескрипторів -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin, що працює лише через дескриптори, все ж постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й надалі ігнорує його. Якщо -`requiresRuntime` пропущено, зберігається застаріла резервна поведінка, щоб наявні Plugin, -які додали дескриптори без цього прапорця, не зламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів +достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише +на дескриптор і не виконуватиме `setup-api` або `openclaw.setupEntry` для +пошуку setup. Якщо plugin, що працює лише через дескриптор, усе ж містить один +із цих записів середовища виконання setup, OpenClaw повідомляє додаткову +діагностику й надалі ігнорує його. Якщо `requiresRuntime` не вказано, +зберігається застаріла резервна поведінка, щоб наявні plugin, які додали +дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані -значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -усіх виявлених Plugin. Неоднозначне володіння завершується відмовою без вибору -переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, яким володіє plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають +залишатися унікальними серед усіх виявлених plugin. Неоднозначне володіння +завершується безпечним блокуванням замість вибору переможця за порядком +виявлення. -Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про -розходження дескрипторів, якщо `setup-api` реєструє провайдера або backend CLI, які -не оголошені в дескрипторах маніфесту, або якщо для дескриптора немає відповідної -runtime-реєстрації. Ця діагностика є додатковою і не відхиляє застарілі Plugin. +Коли середовище виконання setup усе ж виконується, діагностика реєстру setup +повідомляє про розходження дескрипторів, якщо `setup-api` реєструє provider +або backend CLI, яких не оголошують дескриптори маніфесту, або якщо для +дескриптора немає відповідної реєстрації в середовищі виконання. Ці +діагностичні повідомлення є додатковими й не відхиляють застарілі plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, що показується під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env-змінні, які загальні поверхні setup/статусу можуть перевіряти до завантаження runtime Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Так | `string` | Ідентифікатор provider, який показується під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного середовища виконання. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/статусу можуть перевіряти до завантаження середовища виконання plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, що показуються під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup після пошуку за дескриптором виконання `setup-api`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для +рендерингу. ```json { @@ -407,21 +423,22 @@ runtime-реєстрації. Ця діагностика є додатково } ``` -Кожна підказка поля може містити: +Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -прочитати без імпорту runtime Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння +можливостями, які OpenClaw може читати без імпорту середовища виконання +plugin. ```json { @@ -445,46 +462,48 @@ runtime-реєстрації. Ця діагностика є додатково Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ---------------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик extension app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий хук зовнішнього профілю автентифікації належить цьому Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрибування в реальному часі, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів ембедингів пам’яті, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів вебпошуку, якими володіє цей Plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок контрактів вбудованих компонентів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ----------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик extension для app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовища виконання, для яких bundle plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори provider, hook зовнішнього профілю auth яких належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори provider speech, якими володіє цей plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрипції в реальному часі, якими володіє цей plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider голосу в реальному часі, якими володіє цей plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори provider embedding для пам’яті, якими володіє цей plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider розуміння медіа, якими володіє цей plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори provider генерації зображень, якими володіє цей plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори provider генерації відео, якими володіє цей plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори provider web-fetch, якими володіє цей plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори provider web search, якими володіє цей plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори provider імпорту, якими володіє цей plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin для перевірок контрактів bundle. | -`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик -extension app-server лише для Codex. Вбудовані трансформації результатів інструментів мають +`contracts.embeddedExtensionFactories` збережено для фабрик extension лише для +app-server Codex у bundle. Bundle-трансформації результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть -реєструвати middleware результатів інструментів, оскільки цей шов може переписувати -високодовірений вивід інструментів до того, як модель його побачить. +`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugin не можуть +реєструвати middleware результатів інструментів, тому що цей seam може +переписувати високодовірений вивід інструмента до того, як модель його побачить. -Plugin провайдерів, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати -`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через -застарілий сумісний резервний механізм, але він повільніший і буде видалений після -завершення перехідного періоду. +Plugin provider, які реалізують `resolveExternalAuthProfiles`, мають +оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все +ще працюють через застарілий механізм сумісності, але він повільніший і буде +видалений після завершення вікна міграції. -Вбудовані провайдери ембедингів пам’яті мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з -вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway -зареєструє провайдерів. +Bundle provider embedding для пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, +який вони надають, включно з вбудованими адаптерами, такими як `local`. +Окремі шляхи CLI використовують цей контракт маніфесту, щоб завантажувати +лише plugin-власник до того, як повне середовище виконання Gateway зареєструє +provider. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має -типові моделі, пріоритет резервної автоавтентифікації або нативну підтримку документів, які -потрібні загальним допоміжним засобам ядра до завантаження runtime. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли provider розуміння +медіа має типові моделі, пріоритет резервного автоматичного auth або вбудовану +підтримку документів, які потрібні загальним допоміжним засобам core до +завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -508,43 +527,46 @@ Plugin провайдерів, що реалізують `resolveExternalAuthPro } ``` -Кожен запис провайдера може містити: +Кожен запис provider може містити: | Поле | Тип | Що воно означає | | ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові значення “можливість → модель”, які використовуються, коли конфігурація не вказує модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного переходу провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні формати документів, які підтримує провайдер. | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. | +| `defaultModels` | `Record` | Типові значення “можливість → модель”, що використовуються, коли в конфігурації не вказано модель. | +| `autoPriority` | `Record` | Менші числа сортуються вище для автоматичного резервного вибору provider на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані входи документів, які підтримує provider. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження runtime. Виявлення setup/статусу каналу лише для читання може використовувати ці метадані -безпосередньо для налаштованих зовнішніх каналів, якщо запис setup недоступний або -коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. +Використовуйте `channelConfigs`, коли plugin channel потребує дешевих +метаданих конфігурації до завантаження середовища виконання. Виявлення setup/статусу +channel у режимі лише для читання може використовувати ці метадані безпосередньо +для налаштованих зовнішніх channel, коли запис setup недоступний або коли +`setup.requiresRuntime: false` оголошує, що середовище виконання setup не потрібне. -`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ конфігурації користувача -верхнього рівня. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб визначити, якому Plugin належить цей налаштований -канал, до виконання коду runtime Plugin. +`channelConfigs` — це метадані маніфесту plugin, а не новий верхньорівневий +розділ конфігурації користувача. Користувачі, як і раніше, налаштовують +екземпляри channel у `channels.`. OpenClaw читає метадані +маніфесту, щоб визначити, який plugin володіє цим налаштованим channel, до +виконання коду середовища виконання plugin. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні -шляхи: +Для plugin channel `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` валідує `plugins.entries..config` - `channelConfigs..schema` валідує `channels.` -Невбудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні -схеми конфігурації холодного шляху, setup і Control UI не знатимуть форму -параметрів каналу, що належать Plugin, доки не виконається runtime Plugin. +Неbundle plugin, які оголошують `channels[]`, також мають оголошувати +відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити +plugin, але поверхні схем конфігурації холодного шляху, setup і Control UI не +знатимуть форми параметрів, якими володіє channel, доки не виконається +середовище виконання plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок -конфігурації команд, які виконуються до завантаження runtime каналу. Вбудовані канали також можуть -публікувати ті самі типові значення через `package.json#openclaw.channel.commands` разом з -іншими метаданими каталогу каналів, що належать їхньому пакету. +`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` +для перевірок конфігурації команд, які виконуються до завантаження середовища +виконання channel. Bundle channel також можуть публікувати такі самі типові +значення через `package.json#openclaw.channel.commands` разом з іншими +метаданими каталогу channel, якими володіє пакет. ```json { @@ -575,23 +597,24 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Кожен запис каналу може містити: +Кожен запис channel може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI / заповнювачі / підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору та перегляду, коли runtime-метадані ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | -| `commands` | `object` | Статичні автотипові значення нативних команд і нативних Skills для перевірок конфігурації до запуску runtime. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати на поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки щодо чутливості для цього розділу конфігурації channel. | +| `label` | `string` | Мітка channel, що об’єднується з поверхнями вибору та перегляду, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис channel для поверхонь перегляду та каталогу. | +| `commands` | `object` | Статичні автотипові значення для native command і native skill для перевірок конфігурації до запуску середовища виконання. | +| `preferOver` | `string[]` | Ідентифікатори застарілих plugin або plugin із нижчим пріоритетом, які цей channel має випереджати на поверхнях вибору. | -### Заміна іншого Plugin каналу +### Заміна іншого plugin channel -Використовуйте `preferOver`, коли ваш Plugin є пріоритетним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Типові випадки — це перейменований ідентифікатор Plugin, -окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який -зберігає той самий ідентифікатор каналу для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш plugin є бажаним власником для +ідентифікатора channel, який також може надавати інший plugin. Типові випадки +— перейменований ідентифікатор plugin, окремий plugin, що замінює bundle +plugin, або підтримуваний fork, який зберігає той самий ідентифікатор channel +для сумісності конфігурації. ```json { @@ -612,22 +635,24 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та -ідентифікатор пріоритетного Plugin. Якщо менш пріоритетний Plugin було вибрано лише тому, -що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній -runtime-конфігурації, щоб каналом і його інструментами володів один Plugin. Явний вибір -користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw -зберігає цей вибір і повідомляє про діагностику дубльованих каналів/інструментів замість -тихого змінення запитаного набору Plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор channel і +бажаний ідентифікатор plugin. Якщо plugin із нижчим пріоритетом було вибрано +лише тому, що він входить до bundle або увімкнений типово, OpenClaw вимикає +його в ефективній конфігурації середовища виконання, щоб channel і його +інструментами володів один plugin. Явний вибір користувача все одно має +перевагу: якщо користувач явно вмикає обидва plugin, OpenClaw зберігає цей +вибір і повідомляє діагностику дубльованих channel/інструментів замість +мовчазної зміни запитаного набору plugin. -Обмежуйте `preferOver` лише ідентифікаторами Plugin, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` ідентифікаторами plugin, які справді можуть надавати +той самий channel. Це не загальне поле пріоритету і воно не перейменовує +ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з -коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження -runtime Plugin. +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш plugin provider +за скороченими ідентифікаторами моделей на кшталт `gpt-5.5` або +`claude-sonnet-4.6` до завантаження середовища виконання plugin. ```json { @@ -640,26 +665,29 @@ runtime Plugin. OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` власника -- `modelPatterns` мають перевагу над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований - Plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers` + плагіна-власника +- `modelPatterns` мають пріоритет над `modelPrefixes` +- якщо збігаються один небundle plugin і один bundle plugin, перемагає + небundle plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не + вкаже provider Поля: | Поле | Тип | Що воно означає | | --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що перевіряються через `startsWith` для коротких ідентифікаторів моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що перевіряються для коротких ідентифікаторів моделей після видалення суфікса профілю. | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження runtime Plugin. Це джерело, що належить маніфесту, для фіксованих рядків -каталогу, псевдонімів провайдерів, правил приховування та режиму виявлення. Оновлення runtime -і далі належить коду runtime провайдера, але маніфест повідомляє ядру, коли -runtime потрібен. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей +provider до завантаження середовища виконання plugin. Це джерело фіксованих +рядків каталогу, аліасів provider, правил приховування та режиму виявлення, +яким володіє маніфест. Оновлення під час виконання, як і раніше, належить коду +середовища виконання provider, але маніфест повідомляє core, коли середовище +виконання потрібне. ```json { @@ -710,165 +738,219 @@ runtime потрібен. Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `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 з метаданих маніфесту, оновлювати в кеш або чи він потребує середовища виконання. | -Поля провайдера: +Поля provider: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | ------------------------------------------------------------------ | +| `baseUrl` | `string` | Необов’язковий типовий `baseUrl` для моделей у цьому каталозі provider. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі provider. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу provider. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що воно означає | -| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку міркування. | -| `contextWindow` | `number` | Нативне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту runtime, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| Поле | Тип | Що воно означає | +| --------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `id` | `string` | Локальний для provider ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Власне вікно контексту provider. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | | `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | -| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок взагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, яка показується разом зі статусом, відмінним від доступного. | -| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | +| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок взагалі не повинен відображатися. | +| `statusReason` | `string` | Необов’язкова причина, що показується для статусу “не доступно”. | +| `replaces` | `string[]` | Старіші локальні для provider ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для provider ідентифікатор моделі-замінника для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | -Не розміщуйте в `modelCatalog` дані лише для runtime. Якщо провайдеру потрібен -стан облікового запису, API-запит або виявлення локального процесу, щоб знати повний набір -моделей, оголосіть цей провайдер як `refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані лише для середовища виконання. Якщо +provider потребує стану облікового запису, запиту API або виявлення локального +процесу, щоб визначити повний набір моделей, оголосіть цей provider як +`refreshable` або `runtime` у `discovery`. -### Індекс провайдерів OpenClaw +## Довідник `modelPricing` -Індекс провайдерів OpenClaw — це попередні метадані провайдерів, що належать OpenClaw, для провайдерів, -чиї Plugin можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. -Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — -це внутрішній резервний контракт, який використовуватимуть майбутні поверхні -провайдерів для встановлення та засоби вибору моделей до встановлення, коли Plugin провайдера не встановлено. +Використовуйте `modelPricing`, коли provider потребує поведінки цін у +control-plane до завантаження середовища виконання. Кеш цін Gateway читає ці +метадані без імпорту коду середовища виконання provider. + +```json +{ + "providers": ["ollama", "openrouter"], + "modelPricing": { + "providers": { + "ollama": { + "external": false + }, + "openrouter": { + "openRouter": { + "passthroughProviderModel": true + }, + "liteLLM": false + } + } + } +} +``` + +Поля provider: + +| Поле | Тип | Що воно означає | +| ------------ | ----------------- | --------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/self-hosted provider, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Мапінг пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього provider. | +| `liteLLM` | `false \| object` | Мапінг пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього provider. | + +Поля джерела: + +| Поле | Тип | Що воно означає | +| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор provider у зовнішньому каталозі, коли він відрізняється від ідентифікатора provider OpenClaw, наприклад `z-ai` для provider `zai`. | +| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей зі slash як вкладені посилання provider/model; корисно для proxy provider, таких як OpenRouter. | +| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей у зовнішньому каталозі. `version-dots` перевіряє ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | + +### Індекс Provider OpenClaw + +Індекс Provider OpenClaw — це preview-метадані, якими володіє OpenClaw, для +provider, plugin яких ще можуть бути не встановлені. Він не є частиною +маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для +встановлених plugin. Індекс Provider — це внутрішній резервний контракт, який +в майбутньому використовуватимуть поверхні installable-provider і селектори +моделей до встановлення, коли plugin provider не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. `modelCatalog` маніфесту встановленого Plugin. +2. `modelCatalog` маніфесту встановленого plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Попередні рядки Індексу провайдерів OpenClaw. +4. Preview-рядки Індексу Provider OpenClaw. -Індекс провайдерів не повинен містити секрети, стан увімкнення, runtime-хуки чи -актуальні дані моделей, специфічні для облікового запису. Його попередні каталоги використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими -стабільними метаданими відображення, якщо лише поля runtime-адаптера, такі як `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно в узгодженому стані з -маніфестом встановленого Plugin. Провайдери з актуальним виявленням `/models` мають -записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб під час -звичайного виведення списків або онбордингу викликати API провайдера. +Індекс Provider не повинен містити секрети, стан увімкнення, hooks середовища +виконання або живі дані моделей, специфічні для облікового запису. Його +preview-каталоги використовують ту саму форму рядків provider `modelCatalog`, +що й маніфести plugin, але мають обмежуватися стабільними метаданими +відображення, якщо тільки поля адаптера середовища виконання, такі як `api`, +`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно +узгодженими з маніфестом встановленого plugin. Provider із живим виявленням +через `/models` мають записувати оновлені рядки через явний шлях кешу каталогу +моделей, а не змушувати звичайне відображення списків або онбординг викликати +API provider. -Записи Індексу провайдерів також можуть містити метадані Plugin, доступного для встановлення, для провайдерів, -чий Plugin було винесено з ядра або він інакше ще не встановлений. Ці -метадані наслідують шаблон каталогу каналів: назви пакета, специфікації встановлення npm, -очікуваної цілісності та легковагових міток варіантів автентифікації достатньо, щоб показати -варіант setup, доступний для встановлення. Щойно Plugin встановлено, його маніфест отримує перевагу, і запис Індексу провайдерів для цього провайдера ігнорується. +Записи Індексу Provider також можуть містити метадані installable-plugin для +provider, plugin яких було винесено з core або які ще не встановлено. Ці +метадані повторюють шаблон каталогу channel: назви пакета, специфікація +встановлення npm, очікувана цілісність і легковагові мітки варіантів auth +достатні, щоб показати варіант налаштування встановлюваного plugin. Після +встановлення plugin його маніфест має пріоритет, а запис Індексу Provider для +цього provider ігнорується. -Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не розглядає ці поля верхнього рівня як -володіння можливостями. +Застарілі верхньорівневі ключі можливостей є deprecated. Використовуйте +`openclaw doctor --fix`, щоб перемістити `speechProviders`, +`realtimeTranscriptionProviders`, `realtimeVoiceProviders`, +`mediaUnderstandingProviders`, `imageGenerationProviders`, +`videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під +`contracts`; звичайне завантаження маніфесту більше не трактує ці +верхньорівневі поля як володіння можливостями. -## Маніфест і `package.json` +## Маніфест проти package.json Ці два файли виконують різні завдання: -| Файл | Для чого його використовувати | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, контролю встановлення, setup або метаданих каталогу | +| Файл | Для чого його використовувати | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, контролю встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте +таке правило: -- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` +- якщо OpenClaw має знати це до завантаження коду plugin, розмістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розмістіть це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin до запуску runtime навмисно розміщуються в `package.json` у блоці -`openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані plugin, що потрібні до запуску середовища виконання, +навмисно зберігаються в `package.json` у блоці `openclaw`, а не в +`openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує нативні точки входу Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує runtime-точки входу зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Легковагові метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані автотипових значень нативних команд і нативних Skills, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження runtime каналу. | -| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання “чи вже існує налаштування лише через env?” без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання “чи вже десь виконано вхід?” без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із нижньою межею semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує точки входу власного plugin. Має залишатися в каталозі пакета plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript середовища виконання для встановлених пакетів. Має залишатися в каталозі пакета plugin. | +| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення статусу channel/SecretRef у режимі лише для читання. Має залишатися в каталозі пакета plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в каталозі пакета plugin. | +| `openclaw.channel` | Легковагові метадані каталогу channel, такі як мітки, шляхи до документації, аліаси та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані автотипових значень для native command і native skill, які використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження середовища виконання channel. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану auth, які можуть відповісти на запитання «чи вже є якийсь вхід у систему?» без завантаження повного середовища виконання channel. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки щодо встановлення/оновлення для bundle plugin і plugin, опублікованих зовнішньо. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundle plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в -онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються +в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` +повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач +обирає один із цих варіантів. Не переносіть підказки щодо встановлення в +`openclaw.plugin.json`. -`openclaw.install.minHostVersion` перевіряється під час встановлення та завантаження -реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають -Plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але +коректні значення пропускають plugin на старіших хостах. -Точне закріплення версії npm уже існує в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися -безпечною відмовою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. -Інтерактивний онбординг і далі пропонує довірені npm-специфікації реєстру, включно з голими -іменами пакетів і dist-tag, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені за цілісністю, без закріплення цілісності, з невідповідністю -імені пакета та невалідні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає валідного джерела npm, до якого його можна прив’язати. -Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення застосовують його; коли його пропущено, результат розв’язання реєстру -фіксується без закріплення цілісності. +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього +каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки +оновлення завершувалися безпечним блокуванням, якщо отриманий артефакт npm +більше не відповідає закріпленому релізу. Інтерактивний онбординг, як і +раніше, пропонує довірені специфікації npm реєстру, включно з голими назвами +пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти +точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю +назви пакета та з недійсним source default-choice. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає коректного npm source, який можна +закріпити. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення +застосовують його; коли його пропущено, розв’язання реєстру записується без +закріплення за цілісністю. -Plugin каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів -або сканування SecretRef потрібно визначити налаштовані облікові записи без завантаження повного -runtime. Запис setup має надавати метадані каналу разом із безпечними для setup адаптерами -конфігурації, статусу й секретів; мережеві клієнти, слухачі Gateway і transport runtime -мають залишатися в основній точці входу extension. +Plugin channel мають надавати `openclaw.setupEntry`, коли статус, список +channel або сканування SecretRef потребують визначення налаштованих облікових +записів без завантаження повного середовища виконання. Запис setup має +експонувати метадані channel разом із безпечними для setup адаптерами +конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і +transport runtime слід тримати в основній точці входу extension. -Поля runtime-точок входу не скасовують перевірки меж пакета для полів -точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити -завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля точки входу середовища виконання не скасовують перевірки меж пакета для +полів точки входу джерела. Наприклад, `openclaw.runtimeExtensions` не може +зробити шлях `openclaw.extensions`, що виходить за межі пакета, придатним до +завантаження. -`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно -не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам -встановлення відновлюватися після певних збоїв оновлення застарілого вбудованого Plugin, як-от -відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для цього ж -вбудованого Plugin. Інші помилки конфігурації все одно блокують встановлення й спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке +призначення. Він не робить довільні зламані конфігурації придатними для +встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися +після певних застарілих збоїв оновлення bundle plugin, наприклад відсутнього +шляху до bundle plugin або застарілого запису `channels.` для того самого +bundle plugin. Непов’язані помилки конфігурації, як і раніше, блокують +встановлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля -перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного +модуля перевірки: ```json { @@ -884,10 +966,10 @@ runtime. Запис setup має надавати метадані каналу } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка -автентифікації типу yes/no до завантаження повного Plugin каналу. Цільовий експорт має бути -невеликою функцією, яка читає лише збережений стан; не маршрутизуйте її через повний -barrel runtime каналу. +Використовуйте його, коли потокам setup, doctor або configured-state потрібна +дешева перевірка auth “так/ні” до завантаження повного plugin channel. +Цільовий export має бути невеликою функцією, яка лише читає збережений стан; +не маршрутизуйте його через повний barrel середовища виконання channel. `openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: @@ -906,68 +988,71 @@ barrel runtime каналу. } ``` -Використовуйте це, коли канал може визначити налаштований стан через env або інші малі -вхідні дані без runtime. Якщо перевірка потребує повного розв’язання конфігурації або реального -runtime каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. +Використовуйте це, коли channel може визначити налаштований стан на основі env +або інших невеликих невиконавчих вхідних даних. Якщо перевірка потребує +повного розв’язання конфігурації або справжнього середовища виконання channel, +залишайте цю логіку в hook `config.hasConfiguredState` plugin. -## Пріоритет виявлення (однакові ідентифікатори Plugin) +## Пріоритет виявлення (дубльовані ідентифікатори plugin) -OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобально встановлені, робочий простір, явно вибрані в конфігурації шляхи). Якщо два результати виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє plugin із кількох коренів (bundle, глобальне встановлення, +workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені plugin мають +однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; +дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — Plugin, що постачаються разом з OpenClaw -3. **Глобально встановлений** — Plugin, установлені в глобальний корінь Plugin OpenClaw -4. **Робочий простір** — Plugin, виявлені відносно поточного робочого простору +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Bundled** — plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw +4. **Workspace** — plugin, виявлені відносно поточного workspace Наслідки: -- Форк або застаріла копія вбудованого Plugin, що лежить у робочому просторі, не перекриє вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. -- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Fork або застаріла копія bundled plugin у workspace не перекриє bundled-збірку. +- Щоб справді перевизначити bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. +- Відкинуті дублікати записуються в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до схеми JSON +## Вимоги до JSON Schema -- **Кожен Plugin повинен постачати схему JSON**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. +- **Кожен plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня schema є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо лише ідентифікатор каналу не оголошено - маніфестом Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошено в маніфесті plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. -- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але сам Plugin **вимкнений**, конфігурація зберігається, а - у Doctor + логах з’являється **попередження**. + повинні посилатися на **plugin id, які можна виявити**. Невідомі ідентифікатори є **помилками**. +- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи schema, + валідація завершується помилкою, а Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і + в Doctor + журналах з’являється **попередження**. -Див. [Довідник із конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. +Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime і далі завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. -- Нативні маніфести розбираються як JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, доки фінальне значення все ще є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані env-змінних (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Поверхні статусу, аудиту, валідації доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env-змінну налаштованою. -- Для метаданих runtime wizard, які потребують коду провайдера, див. [Хуки runtime провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від нативних модулів, задокументуйте етапи збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест **обов’язковий для власних plugin OpenClaw**, зокрема для завантаження з локальної файлової системи. Середовище виконання, як і раніше, завантажує модуль plugin окремо; маніфест використовується лише для виявлення + валідації. +- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту читає лише документовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запитів. +- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані wizard середовища виконання, які потребують коду provider, дивіться в [Хуки середовища виконання Provider](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugin. + + Початок роботи з plugin. - + Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin і імпорти підшляхів. + Довідник SDK plugin та імпорти підшляхів.