From 43c8e39c259ffffa7ba8a5a4e144a47b1af8def2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 13:01:49 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/model-failover.md | 333 ++++---- docs/uk/gateway/authentication.md | 174 ++-- docs/uk/plugins/architecture.md | 1283 ++++++++++++++-------------- 3 files changed, 895 insertions(+), 895 deletions(-) diff --git a/docs/uk/concepts/model-failover.md b/docs/uk/concepts/model-failover.md index 2ce5a5a69..2f58a9e92 100644 --- a/docs/uk/concepts/model-failover.md +++ b/docs/uk/concepts/model-failover.md @@ -1,55 +1,55 @@ --- read_when: - - Діагностика ротації профілів автентифікації, cooldown або поведінки резервного переходу між моделями + - Діагностика ротації профілів автентифікації, періодів охолодження або поведінки резервного переходу моделей - Оновлення правил резервного переходу для профілів автентифікації або моделей - - Розуміння того, як перевизначення моделі сесії взаємодіють із повторними спробами резервного переходу -summary: Як OpenClaw ротує профілі автентифікації та переходить до резервних моделей -title: Резервне переключення моделей + - Розуміння того, як перевизначення моделі сеансу взаємодіють із повторними спробами резервного переходу +summary: Як OpenClaw перемикає профілі автентифікації та виконує резервний перехід між моделями +title: Резервний перехід моделей x-i18n: - generated_at: "2026-04-05T18:02:10Z" + generated_at: "2026-04-06T12:57:31Z" model: gpt-5.4 provider: openai - source_hash: 899041aa0854e4f347343797649fd11140a01e069e88b1fbc0a76e6b375f6c96 + source_hash: d88821e229610f236bdab3f798d5e8c173f61a77c01017cc87431126bf465e32 source_path: concepts/model-failover.md workflow: 15 --- -# Резервне переключення моделей +# Резервний перехід моделей OpenClaw обробляє збої у два етапи: -1. **Ротація профілю автентифікації** в межах поточного провайдера. +1. **Ротація профілів автентифікації** в межах поточного провайдера. 2. **Резервний перехід моделі** до наступної моделі в `agents.defaults.model.fallbacks`. -У цьому документі пояснюються правила під час виконання та дані, на яких вони ґрунтуються. +У цьому документі пояснюються правила виконання під час роботи та дані, на яких вони ґрунтуються. -## Потік виконання +## Потік виконання під час роботи -Для звичайного текстового запуску OpenClaw оцінює кандидатів у такому порядку: +Для звичайного текстового запуску OpenClaw оцінює кандидати в такому порядку: -1. Поточна вибрана модель сесії. +1. Поточна вибрана модель сеансу. 2. Налаштовані `agents.defaults.model.fallbacks` у заданому порядку. 3. Налаштована основна модель наприкінці, якщо запуск почався з перевизначення. -У межах кожного кандидата OpenClaw спочатку намагається виконати резервний перехід профілю автентифікації, перш ніж перейти -до наступної моделі-кандидата. +У межах кожного кандидата OpenClaw спочатку намагається виконати резервний перехід між профілями автентифікації, перш ніж переходити +до наступного кандидата моделі. -Високорівнева послідовність: +Послідовність верхнього рівня: -1. Визначити активну модель сесії та перевагу профілю автентифікації. -2. Побудувати ланцюжок моделей-кандидатів. -3. Спробувати поточного провайдера з правилами ротації/cooldown профілів автентифікації. -4. Якщо можливості цього провайдера вичерпано через помилку, що допускає резервний перехід, перейти до наступного +1. Визначити активну модель сеансу та пріоритет профілю автентифікації. +2. Побудувати ланцюжок кандидатів моделей. +3. Спробувати поточний провайдер із правилами ротації/охолодження профілів автентифікації. +4. Якщо цей провайдер вичерпано через помилку, що допускає резервний перехід, перейти до наступного кандидата моделі. -5. Зберегти вибране перевизначення резервної моделі до початку повторної спроби, щоб інші читачі - сесії бачили того самого провайдера/модель, яких виконавець ось-ось використає. -6. Якщо кандидат резервної моделі не спрацює, відкотити лише поля перевизначення сесії, що належать резервному переходу, - коли вони все ще відповідають цьому невдалому кандидату. -7. Якщо всі кандидати не спрацюють, згенерувати `FallbackSummaryError` із деталями по кожній спробі - та найближчим часом завершення cooldown, якщо він відомий. +5. Зберегти вибране перевизначення резервного переходу до початку повторної спроби, щоб інші + читачі сеансу бачили того самого провайдера/модель, яких виконавець ось-ось використає. +6. Якщо кандидат резервного переходу завершується помилкою, відкотити лише поля перевизначення сеансу, + що належать резервному переходу, якщо вони все ще відповідають цьому невдалому кандидату. +7. Якщо всі кандидати завершилися помилкою, згенерувати `FallbackSummaryError` із деталями + для кожної спроби та найближчим часом завершення охолодження, якщо його відомо. -Це навмисно вужче за підхід «зберегти й відновити всю сесію». Виконавець -відповіді зберігає лише поля вибору моделі, якими він володіє для резервного переходу: +Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Виконавець +відповідей зберігає лише поля вибору моделі, якими він володіє для резервного переходу: - `providerOverride` - `modelOverride` @@ -57,33 +57,34 @@ OpenClaw обробляє збої у два етапи: - `authProfileOverrideSource` - `authProfileOverrideCompactionCount` -Це запобігає тому, щоб невдала повторна спроба резервного переходу перезаписала новіші, не пов’язані із цим зміни -сесії, такі як ручні зміни `/model` або оновлення ротації сесії, що -сталися під час виконання спроби. +Це запобігає тому, щоб невдала повторна спроба резервного переходу перезаписувала новіші, не пов’язані із цим зміни сеансу, +такі як ручні зміни `/model` або оновлення ротації сеансу, які +відбулися під час виконання спроби. -## Зберігання автентифікації (ключі + OAuth) +## Сховище автентифікації (ключі + OAuth) -OpenClaw використовує **профілі автентифікації** як для ключів API, так і для OAuth-токенів. +OpenClaw використовує **профілі автентифікації** як для API-ключів, так і для токенів OAuth. -- Секрети зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (застаріле: `~/.openclaw/agent/auth-profiles.json`). -- Конфігурація `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів). +- Секрети зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (застарілий шлях: `~/.openclaw/agent/auth-profiles.json`). +- Стан маршрутизації автентифікації під час роботи зберігається в `~/.openclaw/agents//agent/auth-state.json`. +- Конфігурація `auth.profiles` / `auth.order` містить **лише метадані та маршрутизацію** (без секретів). - Застарілий файл OAuth лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання). -Детальніше: [/concepts/oauth](/concepts/oauth) +Докладніше: [/concepts/oauth](/uk/concepts/oauth) Типи облікових даних: - `type: "api_key"` → `{ provider, key }` - `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (+ `projectId`/`enterpriseUrl` для деяких провайдерів) -## Ідентифікатори профілів +## ID профілів -OAuth-входи створюють окремі профілі, щоб можна було співіснувати кільком обліковим записам. +Входи OAuth створюють окремі профілі, щоб могли співіснувати кілька облікових записів. -- Типово: `provider:default`, коли email недоступний. +- За замовчуванням: `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`. ## Порядок ротації @@ -93,75 +94,76 @@ OAuth-входи створюють окремі профілі, щоб можн 2. **Налаштовані профілі**: `auth.profiles`, відфільтровані за провайдером. 3. **Збережені профілі**: записи в `auth-profiles.json` для цього провайдера. -Якщо явний порядок не налаштовано, OpenClaw використовує порядок round-robin: +Якщо явний порядок не налаштовано, OpenClaw використовує порядок round‑robin: -- **Основний ключ:** тип профілю (**OAuth перед ключами API**). -- **Другорядний ключ:** `usageStats.lastUsed` (найдавніші спочатку, у межах кожного типу). -- **Профілі в cooldown/вимкнені** переміщуються в кінець, упорядковані за найближчим завершенням блокування. +- **Основний ключ:** тип профілю (**OAuth перед API-ключами**). +- **Вторинний ключ:** `usageStats.lastUsed` (найдавніші першими в межах кожного типу). +- **Профілі в охолодженні/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим завершенням терміну дії. -### Прикріплення до сесії (дружнє до кешу) +### Закріплення сеансу (сприятливе для кешу) -OpenClaw **закріплює вибраний профіль автентифікації за сесією**, щоб підтримувати кеші провайдера «теплими». -Він **не** виконує ротацію на кожний запит. Закріплений профіль використовується повторно, доки не станеться: +OpenClaw **закріплює вибраний профіль автентифікації за сеансом**, щоб підтримувати кеші провайдера активними. +Він **не** виконує ротацію для кожного запиту. Закріплений профіль використовується повторно, доки: -- скидання сесії (`/new` / `/reset`) -- завершення compaction (лічильник compaction збільшується) -- профіль потрапляє в cooldown/вимикається +- сеанс не скинуто (`/new` / `/reset`) +- не завершиться компакція (лічильник компакції збільшується) +- профіль не перебуває в охолодженні/не вимкнений -Ручний вибір через `/model …@` задає **перевизначення користувача** для цієї сесії -і не ротуватиметься автоматично, доки не почнеться нова сесія. +Ручний вибір через `/model …@` встановлює **перевизначення користувача** для цього сеансу +і не бере участі в автоматичній ротації, доки не почнеться новий сеанс. -Автоматично закріплені профілі (вибрані маршрутизатором сесії) вважаються **перевагою**: -вони перевіряються першими, але OpenClaw може перейти на інший профіль при rate limit/тайм-аутах. -Профілі, закріплені користувачем, залишаються прив’язаними до цього профілю; якщо він не спрацьовує і налаштовано резервні моделі, -OpenClaw переходить до наступної моделі, а не перемикає профілі. +Автоматично закріплені профілі (вибрані маршрутизатором сеансів) розглядаються як **пріоритет**: +їх пробують першими, але OpenClaw може переключитися на інший профіль у разі лімітів швидкості/тайм-аутів. +Профілі, закріплені користувачем, залишаються прив’язаними до цього профілю; якщо він завершується помилкою і налаштовано резервні переходи моделей, +OpenClaw переходить до наступної моделі замість перемикання профілів. ### Чому OAuth може «здаватися втраченим» -Якщо у вас є і OAuth-профіль, і профіль із ключем API для одного провайдера, round-robin може перемикатися між ними між повідомленнями, якщо профілі не закріплено. Щоб примусово використовувати один профіль: +Якщо для одного й того самого провайдера у вас є і профіль OAuth, і профіль API-ключа, round‑robin може перемикатися між ними між повідомленнями, якщо вони не закріплені. Щоб примусово використовувати один профіль: - Закріпіть через `auth.order[provider] = ["provider:profileId"]`, або -- Використайте перевизначення для конкретної сесії через `/model …` із перевизначенням профілю (коли це підтримується вашим UI/поверхнею чату). +- Використовуйте перевизначення для окремого сеансу через `/model …` із перевизначенням профілю (якщо це підтримує ваш UI/поверхня чату). -## Cooldown +## Періоди охолодження -Коли профіль не спрацьовує через помилки автентифікації/rate limit (або тайм-аут, що -схожий на rate limiting), OpenClaw позначає його як такий, що перебуває в cooldown, і переходить до наступного профілю. -Цей кошик rate limit є ширшим за простий `429`: він також включає повідомлення +Коли профіль завершується помилкою через помилки автентифікації/ліміту швидкості (або тайм-аут, схожий +на обмеження швидкості), OpenClaw позначає його як такий, що перебуває в охолодженні, і переходить до наступного профілю. +Ця категорія обмежень швидкості ширша за звичайний `429`: вона також включає повідомлення провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, -`throttled`, `resource exhausted` і періодичні ліміти вікна використання, такі як +`throttled`, `resource exhausted` і періодичні обмеження вікон використання, такі як `weekly/monthly limit reached`. -Помилки формату/некоректного запиту (наприклад, помилки валідації ID виклику інструмента Cloud Code Assist) вважаються такими, що допускають резервний перехід, і використовують ті самі cooldown. -Помилки OpenAI-compatible stop reason, такі як `Unhandled stop reason: error`, +Помилки формату/некоректного запиту (наприклад, помилки валідації ID виклику інструмента Cloud Code Assist) +вважаються такими, що допускають резервний перехід, і використовують ті самі періоди охолодження. +Сумісні з OpenAI помилки причини зупинки, такі як `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали тайм-ауту/резервного переходу. -Загальний текст серверних помилок у межах провайдера також може потрапляти в цей кошик тайм-аутів, якщо -джерело відповідає відомому шаблону тимчасової помилки. Наприклад, для Anthropic просте -`An unknown error occurred` і JSON-пейлоади `api_error` із тимчасовим текстом серверної помилки, таким як -`internal server error`, `unknown error, 520`, `upstream error` -або `backend error`, вважаються такими, що допускають резервний перехід через тайм-аут. Загальний висхідний текст OpenRouter, -наприклад простий `Provider returned error`, також розглядається як -тайм-аут лише тоді, коли контекст провайдера справді є OpenRouter. Загальний внутрішній +Загальний текст серверних помилок на рівні провайдера також може потрапляти до цієї категорії тайм-аутів, коли +джерело відповідає відомому тимчасовому шаблону. Наприклад, у Anthropic просте +`An unknown error occurred` і JSON-повідомлення `api_error` із тимчасовим серверним +текстом, таким як `internal server error`, `unknown error, 520`, `upstream error`, +або `backend error`, вважаються такими, що допускають резервний перехід через тайм-аут. Специфічний для OpenRouter +загальний upstream-текст, такий як просте `Provider returned error`, також розглядається як +тайм-аут, але лише тоді, коли контекст провайдера справді OpenRouter. Загальний внутрішній резервний текст, такий як `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервний перехід. -Cooldown через rate limit також можуть бути прив’язані до моделі: +Періоди охолодження через ліміти швидкості також можуть бути прив’язані до моделі: -- OpenClaw записує `cooldownModel` для помилок rate limit, коли відомий - ідентифікатор моделі, що не спрацювала. -- Сусідню модель у того самого провайдера все ще можна спробувати, коли cooldown - прив’язано до іншої моделі. -- Billing/вікна вимкнення все одно блокують весь профіль у всіх моделях. +- OpenClaw записує `cooldownModel` для збоїв через ліміти швидкості, коли відомо + ID моделі, що завершилася помилкою. +- Споріднена модель у того самого провайдера все ще може бути випробувана, коли охолодження + прив’язане до іншої моделі. +- Вікна білінгу/вимкнення, як і раніше, блокують увесь профіль для всіх моделей. -Cooldown використовують експоненційний backoff: +Періоди охолодження використовують експоненційне збільшення інтервалу: - 1 хвилина - 5 хвилин - 25 хвилин - 1 година (максимум) -Стан зберігається в `auth-profiles.json` у `usageStats`: +Стан зберігається в `auth-state.json` у розділі `usageStats`: ```json { @@ -175,22 +177,22 @@ Cooldown використовують експоненційний backoff: } ``` -## Billing-вимкнення +## Вимкнення через білінг -Помилки billing/кредитів (наприклад, «insufficient credits» / «credit balance too low») вважаються такими, що допускають резервний перехід, але зазвичай вони не є тимчасовими. Замість короткого cooldown OpenClaw позначає профіль як **вимкнений** (з довшим backoff) і переходить до наступного профілю/провайдера. +Збої через білінг/кредити (наприклад, «недостатньо кредитів» / «занадто низький баланс кредитів») вважаються такими, що допускають резервний перехід, але зазвичай вони не є тимчасовими. Замість короткого періоду охолодження OpenClaw позначає профіль як **вимкнений** (із довшим інтервалом зворотного відліку) і переходить до наступного профілю/провайдера. -Не кожна відповідь, схожа на billing, є `402`, і не кожен HTTP `402` потрапляє -сюди. OpenClaw зберігає явний текст billing у гілці billing, навіть коли -провайдер повертає `401` або `403`, але matchers, специфічні для провайдера, залишаються -обмеженими тим провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit -exceeded`). Тим часом тимчасові `402` для вікон використання та -лімітів витрат організації/workspace класифікуються як `rate_limit`, коли +Не кожна відповідь, схожа на проблему з білінгом, має код `402`, і не кожен HTTP `402` потрапляє +сюди. OpenClaw зберігає явний текст, пов’язаний із білінгом, у категорії білінгу навіть тоді, коли +провайдер натомість повертає `401` або `403`, але специфічні для провайдера зіставлення залишаються +обмеженими провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit +exceeded`). Водночас тимчасові `402` помилки вікна використання та +помилки ліміту витрат організації/робочого простору класифікуються як `rate_limit`, коли повідомлення виглядає придатним для повторної спроби (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). -Такі випадки залишаються на шляху короткого cooldown/резервного переходу замість довгого -шляху вимкнення через billing. +Вони залишаються на шляху короткого охолодження/резервного переходу замість довгого +шляху вимкнення через білінг. -Стан зберігається в `auth-profiles.json`: +Стан зберігається в `auth-state.json`: ```json { @@ -203,29 +205,29 @@ limit reached, resets tomorrow` або `organization spending limit exceeded`). } ``` -Типові значення: +Значення за замовчуванням: -- Backoff для billing починається з **5 годин**, подвоюється з кожною помилкою billing і обмежується **24 годинами**. -- Лічильники backoff скидаються, якщо профіль не помилявся протягом **24 годин** (можна налаштувати). -- Для перевантажених повторних спроб дозволяється **1 ротація профілю того самого провайдера** перед переходом до резервної моделі. -- Для перевантажених повторних спроб типово використовується backoff **0 мс**. +- Інтервал зворотного відліку для білінгу починається з **5 годин**, подвоюється з кожним збоєм через білінг і обмежується **24 годинами**. +- Лічильники зворотного відліку скидаються, якщо профіль не зазнавав збоїв протягом **24 годин** (налаштовується). +- Повторні спроби при перевантаженні допускають **1 ротацію профілю того самого провайдера** перед резервним переходом моделі. +- Повторні спроби при перевантаженні за замовчуванням використовують інтервал зворотного відліку **0 мс**. ## Резервний перехід моделі -Якщо всі профілі провайдера не спрацювали, OpenClaw переходить до наступної моделі в -`agents.defaults.model.fallbacks`. Це стосується помилок автентифікації, rate limit і +Якщо всі профілі для провайдера завершилися помилкою, OpenClaw переходить до наступної моделі в +`agents.defaults.model.fallbacks`. Це стосується помилок автентифікації, лімітів швидкості та тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервний перехід). -Перевантаження і помилки rate limit обробляються агресивніше, ніж cooldown billing. -Типово OpenClaw дозволяє одну повторну спробу з іншим профілем того самого провайдера, -а потім без очікування переходить до наступної налаштованої резервної моделі. -Сигнали зайнятості провайдера, такі як `ModelNotReadyException`, потрапляють у цей кошик перевантаження. -Налаштовуйте це через `auth.cooldowns.overloadedProfileRotations`, +Помилки перевантаження та ліміту швидкості обробляються агресивніше, ніж періоди охолодження через білінг. +За замовчуванням OpenClaw дозволяє одну повторну спробу з іншим профілем автентифікації в того самого провайдера, +а потім без очікування перемикається на наступну налаштовану резервну модель. +Сигнали зайнятості провайдера, такі як `ModelNotReadyException`, належать до цієї категорії перевантаження. +Налаштуйте це за допомогою `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. Коли запуск починається з перевизначення моделі (hooks або CLI), резервні переходи все одно завершуються на -`agents.defaults.model.primary` після спроби всіх налаштованих резервних варіантів. +`agents.defaults.model.primary` після спроб усіх налаштованих резервних варіантів. ### Правила ланцюжка кандидатів @@ -235,111 +237,112 @@ OpenClaw будує список кандидатів із поточного з Правила: - Запитана модель завжди перша. -- Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за списком дозволу моделей. - Вони вважаються явним наміром оператора. -- Якщо поточний запуск уже працює на налаштованому резервному варіанті в тій самій родині провайдера, +- Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за списком дозволених + моделей. Вони розглядаються як явний намір оператора. +- Якщо поточний запуск уже використовує налаштований резервний варіант у тому самому сімействі провайдерів, OpenClaw продовжує використовувати весь налаштований ланцюжок. -- Якщо поточний запуск працює на іншому провайдері, ніж у конфігурації, і ця поточна - модель ще не є частиною налаштованого ланцюжка резервного переходу, OpenClaw не - додає непов’язані резервні варіанти з іншого провайдера. -- Коли запуск почався з перевизначення, налаштована основна модель додається в кінці, - щоб ланцюжок міг повернутися до звичайного типового значення після вичерпання +- Якщо поточний запуск використовує іншого провайдера, ніж у конфігурації, і ця поточна + модель ще не є частиною налаштованого ланцюжка резервних варіантів, OpenClaw не + додає непов’язані налаштовані резервні варіанти від іншого провайдера. +- Коли запуск почався з перевизначення, налаштована основна модель додається в + кінець, щоб ланцюжок міг повернутися до звичайного значення за замовчуванням після вичерпання попередніх кандидатів. ### Які помилки просувають резервний перехід -Резервний перехід моделі продовжується у випадках: +Резервний перехід моделі продовжується за таких умов: - збої автентифікації -- rate limit і вичерпання cooldown +- ліміти швидкості та вичерпання періоду охолодження - помилки перевантаження/зайнятості провайдера - помилки резервного переходу, схожі на тайм-аут -- вимкнення через billing -- `LiveSessionModelSwitchError`, який нормалізується в шлях резервного переходу, щоб +- вимкнення через білінг +- `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного переходу, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб -- інші нерозпізнані помилки, коли ще залишилися кандидати +- інші нерозпізнані помилки, коли ще залишаються кандидати -Резервний перехід моделі не продовжується у випадках: +Резервний перехід моделі не продовжується за таких умов: -- явне переривання, яке не схоже на тайм-аут/помилку резервного переходу -- помилки переповнення контексту, які мають залишатися в логіці 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 +### Поведінка пропуску через охолодження та пробних спроб -Коли всі профілі автентифікації провайдера вже перебувають у cooldown, OpenClaw +Коли всі профілі автентифікації для провайдера вже перебувають в охолодженні, OpenClaw не пропускає цього провайдера автоматично назавжди. Він ухвалює рішення для кожного кандидата окремо: -- Стійкі збої автентифікації негайно пропускають увесь провайдер. -- Вимкнення через billing зазвичай пропускаються, але основного кандидата все ще можна probe - з throttling, щоб відновлення було можливе без перезапуску. -- Основного кандидата можна probe ближче до завершення cooldown із throttling для кожного провайдера. -- Сусідні резервні моделі того самого провайдера можна спробувати попри cooldown, якщо - збій виглядає тимчасовим (`rate_limit`, `overloaded` або unknown). Це - особливо важливо, коли rate limit прив’язано до моделі і сусідня модель може - одразу відновитися. -- Тимчасові cooldown probe обмежуються однією спробою на провайдера в межах одного резервного запуску, щоб +- Стійкі збої автентифікації відразу пропускають увесь провайдер. +- Вимкнення через білінг зазвичай пропускаються, але основного кандидата все одно можна пробно перевірити + із обмеженням частоти, щоб відновлення було можливим без перезапуску. +- Основного кандидата можна пробно перевірити ближче до завершення періоду охолодження, з + обмеженням частоти для кожного провайдера. +- Резервні споріднені моделі того самого провайдера можна пробувати попри охолодження, коли + збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). + Це особливо важливо, коли обмеження швидкості прив’язане до моделі, а споріднена модель може + все ще відновитися негайно. +- Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера за один запуск резервного переходу, щоб один провайдер не затримував міжпровайдерний резервний перехід. -## Перевизначення сесії та живе перемикання моделі +## Перевизначення сеансу та живе перемикання моделі -Зміни моделі сесії — це спільний стан. Активний виконавець, команда `/model`, -оновлення compaction/сесії та узгодження живої сесії читають або записують -частини того самого запису сесії. +Зміни моделі сеансу — це спільний стан. Активний виконавець, команда `/model`, +оновлення компакції/сеансу та узгодження живого сеансу читають або записують +частини одного й того самого запису сеансу. -Це означає, що повторні спроби резервного переходу мають координуватися з живим перемиканням моделі: +Це означає, що повторні спроби резервного переходу мають узгоджуватися з живим перемиканням моделі: - Лише явні зміни моделі, ініційовані користувачем, позначають очікуване живе перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`. - Зміни моделі, ініційовані системою, такі як ротація резервного переходу, - перевизначення heartbeat або compaction, самі по собі ніколи не позначають очікуване живе перемикання. -- Перед початком повторної спроби резервного переходу виконавець відповіді зберігає вибрані - поля перевизначення резервного переходу в запис сесії. -- Узгодження живої сесії надає перевагу збереженим перевизначенням сесії над застарілими + перевизначення heartbeat або компакція, самі по собі ніколи не позначають очікуване живе перемикання. +- Перш ніж почнеться повторна спроба резервного переходу, виконавець відповідей зберігає вибрані + поля перевизначення резервного переходу в запис сеансу. +- Узгодження живого сеансу віддає перевагу збереженим перевизначенням сеансу перед застарілими полями моделі під час виконання. -- Якщо спроба резервного переходу не спрацює, виконавець відкочує лише ті поля перевизначення, - які він записав, і лише якщо вони все ще відповідають невдалому кандидату. +- Якщо спроба резервного переходу завершується помилкою, виконавець відкочує лише ті поля перевизначення, + які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. Це запобігає класичній гонці: -1. Основна модель не спрацьовує. -2. Кандидат резервної моделі вибирається в пам’яті. -3. У сховищі сесії все ще вказано стару основну модель. -4. Узгодження живої сесії читає застарілий стан сесії. -5. Повторну спробу відкидає назад на стару модель до початку спроби резервного переходу. +1. Основний варіант завершується помилкою. +2. Кандидат резервного переходу вибирається в пам’яті. +3. Сховище сеансу все ще вказує старий основний варіант. +4. Узгодження живого сеансу читає застарілий стан сеансу. +5. Повторна спроба повертається до старої моделі ще до початку спроби резервного переходу. -Збережене перевизначення резервної моделі закриває це вікно, а вузький відкат -зберігає новіші ручні або runtime-зміни сесії без змін. +Збережене перевизначення резервного переходу закриває це вікно, а вузький відкат +зберігає новіші ручні зміни або зміни сеансу під час виконання. -## Спостережуваність і підсумки збоїв +## Спостережуваність і зведення помилок -`runWithModelFallback(...)` записує деталі кожної спроби, які потрапляють у журнали та -повідомлення користувача про cooldown: +`runWithModelFallback(...)` записує деталі кожної спроби, які використовуються для журналів і +повідомлень для користувача про період охолодження: -- спроба provider/model +- спроба `provider/model` - причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного переходу) - необов’язковий status/code -- зрозумілий для людини підсумок помилки +- зрозуміле людині зведення помилки -Коли всі кандидати не спрацьовують, OpenClaw генерує `FallbackSummaryError`. Зовнішній -виконавець відповіді може використати це, щоб побудувати точніше повідомлення на кшталт «усі моделі -тимчасово обмежені через rate limit» і додати найближчий час завершення cooldown, якщо він відомий. +Коли всі кандидати завершуються помилкою, OpenClaw генерує `FallbackSummaryError`. Зовнішній +виконавець відповідей може використати це для побудови точнішого повідомлення, наприклад «усі моделі +тимчасово обмежені за швидкістю», і включити найближчий час завершення періоду охолодження, якщо його відомо. -Цей підсумок cooldown враховує модель: +Це зведення про охолодження враховує модель: -- непов’язані rate limit, прив’язані до інших моделей, ігноруються для ланцюжка - спроб provider/model -- якщо блокування, що залишилося, є відповідним rate limit, прив’язаним до моделі, OpenClaw - повідомляє останній відповідний час завершення, який все ще блокує цю модель +- не пов’язані з поточним ланцюжком `provider/model` обмеження швидкості, прив’язані до моделі, + ігноруються +- якщо блокування, що залишилося, є відповідним обмеженням швидкості, прив’язаним до моделі, OpenClaw + повідомляє про останній відповідний час завершення, який усе ще блокує цю модель ## Пов’язана конфігурація -Див. [Конфігурація шлюзу](/gateway/configuration), щоб дізнатися про: +Див. [Конфігурація Gateway](/uk/gateway/configuration) для: - `auth.profiles` / `auth.order` - `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider` @@ -347,6 +350,6 @@ length exceeded`) - `auth.cooldowns.overloadedProfileRotations` / `auth.cooldowns.overloadedBackoffMs` - `auth.cooldowns.rateLimitedProfileRotations` - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` -- маршрутизацію `agents.defaults.imageModel` +- маршрутизація `agents.defaults.imageModel` -Ширший огляд вибору моделей і резервного переходу див. у [Моделі](/concepts/models). +Див. [Моделі](/uk/concepts/models), щоб отримати ширший огляд вибору моделей і резервного переходу. diff --git a/docs/uk/gateway/authentication.md b/docs/uk/gateway/authentication.md index 88f977b71..8902064c5 100644 --- a/docs/uk/gateway/authentication.md +++ b/docs/uk/gateway/authentication.md @@ -1,51 +1,51 @@ --- read_when: - - Налагодження auth моделі або завершення строку дії OAuth + - Налагодження автентифікації моделей або завершення строку дії OAuth - Документування автентифікації або зберігання облікових даних -summary: 'Автентифікація моделей: OAuth, API ключі та застарілий setup-token Anthropic' +summary: 'Автентифікація моделей: OAuth, API-ключі та застарілий setup-token Anthropic' title: Автентифікація x-i18n: - generated_at: "2026-04-05T18:03:09Z" + generated_at: "2026-04-06T12:57:04Z" model: gpt-5.4 provider: openai - source_hash: f59ede3fcd7e692ad4132287782a850526acf35474b5bfcea29e0e23610636c2 + source_hash: b13cc0bca2b27a6d8326a8cb3f8b1e1810ecd722f29c7a199ceff2fbaf70c6aa source_path: gateway/authentication.md workflow: 15 --- -# Автентифікація (Провайдери моделей) +# Автентифікація (постачальники моделей) -Ця сторінка описує автентифікацію **провайдера моделей** (API ключі, OAuth і застарілий Anthropic setup-token). Для автентифікації **підключення gateway** (token, password, trusted-proxy) див. [Configuration](/gateway/configuration) і [Trusted Proxy Auth](/gateway/trusted-proxy-auth). +Ця сторінка охоплює автентифікацію **постачальника моделей** (API-ключі, OAuth і застарілий setup-token Anthropic). Для автентифікації **підключення шлюзу** (токен, пароль, trusted-proxy) див. [Configuration](/uk/gateway/configuration) і [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). -OpenClaw підтримує OAuth і API ключі для провайдерів моделей. Для постійно -увімкнених хостів gateway API ключі зазвичай є найбільш передбачуваним варіантом. Потоки -передплати/OAuth також підтримуються, коли вони відповідають моделі облікового запису вашого провайдера. +OpenClaw підтримує OAuth і API-ключі для постачальників моделей. Для хостів +шлюзу, що працюють постійно, API-ключі зазвичай є найпередбачуванішим варіантом. Також +підтримуються потоки підписки/OAuth, якщо вони відповідають моделі облікового запису вашого постачальника. -Див. [/concepts/oauth](/concepts/oauth) для повного потоку OAuth і структури +Див. [/concepts/oauth](/uk/concepts/oauth), щоб ознайомитися з повним потоком OAuth і схемою зберігання. -Для auth на основі SecretRef (providers `env`/`file`/`exec`) див. [Secrets Management](/gateway/secrets). -Для правил допустимості облікових даних/кодів причин, які використовує `models status --probe`, див. -[Auth Credential Semantics](/auth-credential-semantics). +Щодо автентифікації на основі SecretRef (постачальники `env`/`file`/`exec`) див. [Secrets Management](/uk/gateway/secrets). +Щодо правил відповідності облікових даних/кодів причин, які використовує `models status --probe`, див. +[Auth Credential Semantics](/uk/auth-credential-semantics). -## Рекомендоване налаштування (API ключ, будь-який провайдер) +## Рекомендоване налаштування (API-ключ, будь-який постачальник) -Якщо ви запускаєте довготривалий gateway, почніть з API ключа для обраного -провайдера. -Зокрема для Anthropic auth через API ключ є безпечним шляхом. Auth Anthropic у стилі -передплати всередині OpenClaw — це застарілий шлях setup-token, і його -слід розглядати як шлях **Extra Usage**, а не як шлях лімітів плану. +Якщо ви запускаєте довготривалий шлюз, почніть з API-ключа для вибраного +постачальника. +Для Anthropic зокрема, автентифікація через API-ключ є безпечним шляхом. Автентифікація Anthropic +у стилі підписки в OpenClaw — це застарілий шлях setup-token, і її +слід розглядати як шлях **Extra Usage**, а не як шлях лімітів тарифного плану. -1. Створіть API ключ у консолі вашого провайдера. -2. Розмістіть його на **хості gateway** (машині, де виконується `openclaw gateway`). +1. Створіть API-ключ у консолі вашого постачальника. +2. Розмістіть його на **хості шлюзу** (машині, на якій виконується `openclaw gateway`). ```bash export _API_KEY="..." openclaw models status ``` -3. Якщо Gateway працює під systemd/launchd, краще додати ключ у +3. Якщо Gateway працює під systemd/launchd, краще розмістити ключ у `~/.openclaw/.env`, щоб демон міг його прочитати: ```bash @@ -61,44 +61,44 @@ openclaw models status openclaw doctor ``` -Якщо ви не хочете самостійно керувати env vars, onboarding може зберігати -API ключі для використання демоном: `openclaw onboard`. +Якщо ви не хочете самостійно керувати змінними середовища, onboarding може зберігати +API-ключі для використання демоном: `openclaw onboard`. -Див. [Help](/help) для подробиць про успадкування env (`env.shellEnv`, +Див. [Help](/uk/help), щоб дізнатися подробиці про успадкування env (`env.shellEnv`, `~/.openclaw/.env`, systemd/launchd). -## Anthropic: сумісність із застарілим токеном +## Anthropic: сумісність із застарілими токенами -Auth через setup-token Anthropic все ще доступна в OpenClaw як -застарілий/ручний шлях. Публічна документація Anthropic для Claude Code все ще описує пряме використання -Claude Code у терміналі в межах планів Claude, але Anthropic окремо повідомив користувачам -OpenClaw, що шлях входу Claude в **OpenClaw** вважається використанням стороннього -harness і вимагає **Extra Usage**, що оплачується окремо від -передплати. +Автентифікація Anthropic setup-token усе ще доступна в OpenClaw як +застарілий/ручний шлях. Публічна документація Anthropic Claude Code і далі охоплює пряме +використання Claude Code у терміналі в межах тарифів Claude, але Anthropic окремо повідомила +користувачам OpenClaw, що шлях входу Claude в **OpenClaw** вважається використанням +стороннього harness і потребує **Extra Usage**, що оплачується окремо від +підписки. -Для найзрозумілішого шляху налаштування використовуйте API ключ Anthropic. Якщо вам потрібно зберегти -шлях Anthropic у стилі передплати в OpenClaw, використовуйте застарілий шлях setup-token +Для найзрозумілішого шляху налаштування використовуйте API-ключ Anthropic. Якщо вам потрібно зберегти +шлях Anthropic у стилі підписки в OpenClaw, використовуйте застарілий шлях setup-token з очікуванням, що Anthropic розглядатиме це як **Extra Usage**. -Ручне введення токена (будь-який провайдер; записує `auth-profiles.json` + оновлює config): +Ручне введення токена (будь-який постачальник; записує в `auth-profiles.json` + оновлює config): ```bash openclaw models auth paste-token --provider openrouter ``` -Також підтримуються посилання на auth profile для статичних облікових даних: +Також підтримуються посилання на профілі автентифікації для статичних облікових даних: -- облікові дані `api_key` можуть використовувати `keyRef: { source, provider, id }` -- облікові дані `token` можуть використовувати `tokenRef: { source, provider, id }` -- Профілі в режимі OAuth не підтримують облікові дані SecretRef; якщо `auth.profiles..mode` встановлено в `"oauth"`, вхідні `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляються. +- Облікові дані `api_key` можуть використовувати `keyRef: { source, provider, id }` +- Облікові дані `token` можуть використовувати `tokenRef: { source, provider, id }` +- Профілі режиму OAuth не підтримують облікові дані SecretRef; якщо для `auth.profiles..mode` встановлено `"oauth"`, введення `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється. -Перевірка, зручна для автоматизації (код виходу `1`, якщо строк дії завершився/відсутній, `2`, якщо строк дії скоро завершиться): +Перевірка, зручна для автоматизації (вихід `1`, якщо строк дії минув/відсутній, `2`, якщо скоро мине): ```bash openclaw models status --check ``` -Live probes auth: +Живі перевірки автентифікації: ```bash openclaw models status --probe @@ -106,66 +106,66 @@ openclaw models status --probe Примітки: -- Рядки probe можуть походити з auth profiles, облікових даних env або `models.json`. -- Якщо явний `auth.order.` пропускає збережений profile, probe повідомляє - `excluded_by_auth_order` для цього profile замість спроби його використати. -- Якщо auth існує, але OpenClaw не може визначити кандидата моделі для probe для - цього провайдера, probe повідомляє `status: no_model`. -- Cooldown через rate limit можуть бути прив’язані до моделі. Profile у cooldown для однієї - моделі все ще може бути придатним для спорідненої моделі того самого провайдера. +- Рядки probe можуть надходити з профілів автентифікації, облікових даних env або `models.json`. +- Якщо явний `auth.order.` пропускає збережений профіль, probe повідомляє + `excluded_by_auth_order` для цього профілю замість спроби використати його. +- Якщо автентифікація існує, але OpenClaw не може визначити кандидата моделі для probe + для цього постачальника, probe повідомляє `status: no_model`. +- Затримки охолодження через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується для однієї + моделі, усе ще може бути придатним для спорідненої моделі того самого постачальника. -Необов’язкові scripts для ops (systemd/Termux) описані тут: -[Auth monitoring scripts](/help/scripts#auth-monitoring-scripts) +Необов’язкові операційні скрипти (systemd/Termux) задокументовані тут: +[Auth monitoring scripts](/uk/help/scripts#auth-monitoring-scripts) ## Примітка щодо Anthropic -Backend Anthropic `claude-cli` було видалено. +Бекенд Anthropic `claude-cli` було видалено. -- Використовуйте API ключі Anthropic для трафіку Anthropic в OpenClaw. -- Setup-token Anthropic залишається застарілим/ручним шляхом і має використовуватися з - очікуванням білінгу Extra Usage, про який Anthropic повідомив користувачам OpenClaw. +- Використовуйте API-ключі Anthropic для трафіку Anthropic в OpenClaw. +- Anthropic setup-token залишається застарілим/ручним шляхом і має використовуватися з + очікуванням тарифікації Extra Usage, про яку Anthropic повідомила користувачам OpenClaw. - `openclaw doctor` тепер виявляє застарілий видалений стан Anthropic Claude CLI. Якщо - байти збережених облікових даних усе ще існують, doctor перетворює їх назад у - профілі Anthropic token/OAuth. Якщо ні, doctor видаляє застарілу конфігурацію Claude CLI - і вказує вам на відновлення через API ключ або setup-token. + байти збережених облікових даних усе ще існують, doctor перетворює їх назад на + профілі токена/OAuth Anthropic. Якщо ні, doctor видаляє застарілу конфігурацію Claude CLI + і вказує вам на відновлення через API-ключ або setup-token. -## Перевірка стану auth моделі +## Перевірка стану автентифікації моделі ```bash openclaw models status openclaw doctor ``` -## Поведінка ротації API ключів (gateway) +## Поведінка ротації API-ключів (шлюз) -Деякі провайдери підтримують повторну спробу запиту з альтернативними ключами, коли виклик API -натрапляє на rate limit провайдера. +Деякі постачальники підтримують повторну спробу запиту з альтернативними ключами, коли виклик API +натрапляє на обмеження частоти постачальника. - Порядок пріоритету: - - `OPENCLAW_LIVE__KEY` (одне перевизначення) + - `OPENCLAW_LIVE__KEY` (єдиний override) - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` -- Провайдери Google також включають `GOOGLE_API_KEY` як додатковий fallback. +- Постачальники Google також включають `GOOGLE_API_KEY` як додатковий резервний варіант. - Той самий список ключів дедуплікується перед використанням. -- OpenClaw повторює спробу з наступним ключем лише для помилок rate limit (наприклад +- OpenClaw виконує повторну спробу з наступним ключем лише для помилок обмеження частоти (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached` або `workers_ai ... quota limit exceeded`). -- Помилки, не пов’язані з rate limit, не повторюються з альтернативними ключами. -- Якщо всі ключі не спрацювали, повертається фінальна помилка з останньої спроби. +- Помилки, не пов’язані з обмеженням частоти, не повторюються з альтернативними ключами. +- Якщо всі ключі не спрацюють, повертається остаточна помилка з останньої спроби. ## Керування тим, які облікові дані використовуються -### Для сесії (команда чату) +### Для сеансу (команда чату) -Використовуйте `/model @`, щоб закріпити конкретні облікові дані провайдера для поточної сесії (приклади id профілів: `anthropic:default`, `anthropic:work`). +Використовуйте `/model @`, щоб закріпити конкретні облікові дані постачальника для поточного сеансу (приклади ідентифікаторів профілів: `anthropic:default`, `anthropic:work`). -Використовуйте `/model` (або `/model list`) для компактного вибору; використовуйте `/model status` для повного перегляду (кандидати + наступний auth profile, а також подробиці endpoint провайдера, якщо налаштовано). +Використовуйте `/model` (або `/model list`) для компактного вибору; використовуйте `/model status` для повного подання (кандидати + наступний профіль автентифікації, а також відомості про endpoint постачальника, якщо їх налаштовано). -### Для агента (перевизначення CLI) +### Для агента (override CLI) -Установіть явне перевизначення порядку auth profile для агента (зберігається в `auth-profiles.json` цього агента): +Установіть явний override порядку профілів автентифікації для агента (зберігається в `auth-state.json` цього агента): ```bash openclaw models auth order get --provider anthropic @@ -173,36 +173,36 @@ openclaw models auth order set --provider anthropic anthropic:default openclaw models auth order clear --provider anthropic ``` -Використовуйте `--agent `, щоб націлитися на конкретного агента; не вказуйте його, щоб використати налаштованого агента за замовчуванням. -Коли ви налагоджуєте проблеми з порядком, `openclaw models status --probe` показує пропущені -збережені profiles як `excluded_by_auth_order` замість того, щоб мовчки їх пропускати. -Коли ви налагоджуєте проблеми з cooldown, пам’ятайте, що cooldown через rate limit можуть бути прив’язані -до одного id моделі, а не до всього profile провайдера. +Використовуйте `--agent `, щоб націлити на конкретного агента; не вказуйте його, щоб використовувати налаштованого агента за замовчуванням. +Під час налагодження проблем із порядком `openclaw models status --probe` показує пропущені +збережені профілі як `excluded_by_auth_order` замість того, щоб мовчки їх пропускати. +Під час налагодження проблем із затримками охолодження пам’ятайте, що вони можуть бути прив’язані +до одного id моделі, а не до всього профілю постачальника. ## Усунення несправностей -### "No credentials found" +### "Облікові дані не знайдено" -Якщо profile Anthropic відсутній, налаштуйте API ключ Anthropic на -**хості gateway** або налаштуйте застарілий шлях setup-token Anthropic, а потім повторно перевірте: +Якщо профіль Anthropic відсутній, налаштуйте API-ключ Anthropic на +**хості шлюзу** або налаштуйте застарілий шлях Anthropic setup-token, а потім повторно перевірте: ```bash openclaw models status ``` -### Термін дії токена спливає/сплив +### Строк дії токена скоро минає/минув -Запустіть `openclaw models status`, щоб підтвердити, у якого profile спливає строк дії. Якщо застарілий -profile токена Anthropic відсутній або строк його дії завершився, оновіть це налаштування через -setup-token або перейдіть на API ключ Anthropic. +Виконайте `openclaw models status`, щоб підтвердити, строк дії якого профілю скоро минає. Якщо застарілий +профіль токена Anthropic відсутній або строк його дії минув, оновіть це налаштування через +setup-token або перейдіть на API-ключ Anthropic. Якщо на машині все ще є застарілий видалений стан Anthropic Claude CLI зі старіших -збірок, запустіть: +збірок, виконайте: ```bash openclaw doctor --yes ``` -Doctor перетворює `anthropic:claude-cli` назад на Anthropic token/OAuth, якщо -збережені байти облікових даних усе ще існують. Інакше він видаляє застарілі -посилання на profile/config/model Claude CLI і залишає вказівки щодо наступних кроків. +Doctor перетворює `anthropic:claude-cli` назад на токен/OAuth Anthropic, якщо +байти збережених облікових даних усе ще існують. Інакше він видаляє застарілі +посилання профілю/конфігурації/моделі Claude CLI і залишає вказівки щодо наступних кроків. diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 1047abc36..2ce4efe6a 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -3,184 +3,183 @@ read_when: - Створення або налагодження нативних плагінів OpenClaw - Розуміння моделі можливостей плагінів або меж володіння - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація хуків часу виконання постачальника або плагінів каналів + - Реалізація хуків середовища виконання провайдера або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішні механізми плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' -title: Внутрішні механізми плагінів +summary: 'Внутрішня будова плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' +title: Внутрішня будова плагінів x-i18n: - generated_at: "2026-04-06T12:47:19Z" + generated_at: "2026-04-06T13:01:49Z" model: gpt-5.4 provider: openai - source_hash: b2f7f48bd5599b9897aa851fb25d501d9643d76f66084f5867b3866fec91cef6 + source_hash: 8780d364f6784e4d44b4160f5c6b24fe34aaf31dec1b6ac5b06a90d54ac0403c source_path: plugins/architecture.md workflow: 15 --- -# Внутрішні механізми плагінів +# Внутрішня будова плагінів - Це **довідник з глибокої архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача - - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна + Це **довідник із глибокої архітектури**. Практичні посібники див. тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення плагіна - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей + - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації -Ця сторінка охоплює внутрішню архітектуру системи плагінів OpenClaw. +На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен +Можливості — це публічна модель **нативних плагінів** всередині OpenClaw. Кожен нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади плагінів | -| --------------------- | ----------------------------------------------- | ------------------------------------ | -| Текстовий висновок | `api.registerProvider(...)` | `openai`, `anthropic` | -| Бекенд висновку CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Можливість | Метод реєстрації | Приклади плагінів | +| --------------------- | ---------------------------------------------- | ------------------------------------ | +| Текстовий висновок | `api.registerProvider(...)` | `openai`, `anthropic` | +| Бекенд висновку CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або -служби, є **застарілим плагіном лише з хуками**. Цей шаблон і далі повністю підтримується. +сервіси, є **застарілим плагіном лише з хуками**. Цей шаблон усе ще повністю підтримується. ### Позиція щодо зовнішньої сумісності Модель можливостей уже інтегрована в ядро та сьогодні використовується вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще -потребує вищої планки, ніж «це експортується, отже це заморожено». +потребує вищої планки, ніж «це експортується, отже воно заморожене». Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; розглядайте - це як базовий рівень сумісності -- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей, а не - vendor-специфічним зверненням усередину чи новим схемам лише з хуками -- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але розглядайте - допоміжні поверхні, специфічні для можливостей, як такі, що еволюціонують, якщо документація - явно не позначає контракт як стабільний +- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте + це базовим рівнем сумісності +- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей замість + вендор-специфічних проникнень усередину або нових конструкцій лише з хуками +- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але вважайте + допоміжні поверхні, специфічні для можливостей, такими, що ще розвиваються, якщо документація + прямо не позначає контракт як стабільний Практичне правило: -- API реєстрації можливостей — це бажаний напрямок -- застарілі хуки залишаються найбезпечнішим шляхом без ламання для зовнішніх плагінів під час +- API реєстрації можливостей — це бажаний напрям +- застарілі хуки залишаються найбезпечнішим шляхом без поломок для зовнішніх плагінів під час переходу -- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому документованому - контракту, а не випадковим експортам допоміжних засобів +- не всі експортовані допоміжні підшляхи однаково важливі; віддавайте перевагу вузькому + задокументованому контракту, а не випадковим допоміжним експортам ### Форми плагінів OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки під час реєстрації, а не лише статичних метаданих: +поведінки реєстрації, а не лише статичних метаданих: -- **plain-capability** — реєструє рівно один тип можливості (наприклад, - плагін лише постачальника, як-от `mistral`) -- **hybrid-capability** — реєструє кілька типів можливостей (наприклад, +- **plain-capability** -- реєструє рівно один тип можливості (наприклад, + плагін лише провайдера, такий як `mistral`) +- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим висновком, мовленням, розумінням медіа та генерацією зображень) -- **hook-only** — реєструє лише хуки (типізовані або користувацькі), без можливостей, - інструментів, команд чи служб -- **non-capability** — реєструє інструменти, команди, служби або маршрути, але без - можливостей +- **hook-only** -- реєструє лише хуки (типізовані або власні), без можливостей, + інструментів, команд чи сервісів +- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості -Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та розклад -його можливостей. Подробиці дивіться в [довіднику CLI](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та +розподіл можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). ### Застарілі хуки Хук `before_agent_start` залишається підтримуваним як шлях сумісності для -плагінів лише з хуками. Застарілі реальні плагіни все ще залежать від нього. +плагінів лише з хуками. Застарілі реальні плагіни досі від нього залежать. Напрямок: - зберігати його працездатність -- документувати його як застарілий -- для роботи з перевизначенням моделі/постачальника віддавати перевагу `before_model_resolve` -- для змінення prompt віддавати перевагу `before_prompt_build` -- видаляти лише після зниження реального використання та коли покриття фікстурами підтвердить безпеку міграції +- документувати як застарілий +- для перевизначення моделі/провайдера віддавати перевагу `before_model_resolve` +- для змінювання prompt віддавати перевагу `before_prompt_build` +- прибирати лише після зниження реального використання та підтвердження безпечної міграції покриттям фікстур ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити -одну з таких позначок: +один із цих маркерів: | Сигнал | Значення | | ------------------------ | ------------------------------------------------------------ | -| **config valid** | Конфігурація успішно розбирається, а плагіни успішно визначаються | +| **config valid** | Конфігурація коректно розбирається, і плагіни успішно визначаються | | **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | +| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | +| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | -Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш плагін — -`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці -сигнали також відображаються в `openclaw status --all` і `openclaw plugins doctor`. +Ані `hook-only`, ані `before_agent_start` не зламають ваш плагін сьогодні -- +`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці +сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить кандидатів у плагіни в налаштованих шляхах, коренях workspace, - глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку читає нативні - маніфести `openclaw.plugin.json`, а також підтримувані маніфести пакетів. + OpenClaw знаходить кандидатів у плагіни з налаштованих шляхів, коренів робочого простору, + глобальних коренів розширень і вбудованих розширень. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json` та підтримувані маніфести пакетів. 2. **Увімкнення + валідація** Ядро вирішує, чи знайдений плагін увімкнений, вимкнений, заблокований або вибраний для ексклюзивного слота, наприклад пам’яті. -3. **Завантаження часу виконання** - Нативні плагіни OpenClaw завантажуються в межах процесу через jiti і реєструють +3. **Завантаження середовища виконання** + Нативні плагіни OpenClaw завантажуються в межах процесу через jiti та реєструють можливості в центральному реєстрі. Сумісні пакети нормалізуються в записи - реєстру без імпорту коду часу виконання. -4. **Споживання поверхні** - Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування постачальників, - хуки, HTTP-маршрути, команди CLI та служби. + реєстру без імпорту коду середовища виконання. +4. **Споживання поверхонь** + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування провайдерів, + хуки, HTTP-маршрути, команди CLI та сервіси. -Зокрема для CLI плагінів, виявлення кореневих команд поділено на дві фази: +Для CLI плагінів зокрема, виявлення кореневих команд розділено на дві фази: - метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI плагіна може залишатися лінивим і реєструватися при першому виклику +- справжній модуль CLI плагіна може залишатися ледачим і реєструватися під час першого виклику -Це дає змогу зберігати код CLI, що належить плагіну, всередині плагіна, водночас дозволяючи OpenClaw -резервувати імена кореневих команд до розбору. +Це дозволяє зберігати код CLI, що належить плагіну, всередині плагіна, водночас +дозволяючи OpenClaw резервувати імена кореневих команд до розбору. -Важлива межа дизайну: +Важлива межа проєктування: - виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** без виконання коду плагіна -- нативна поведінка часу виконання походить із шляху `register(api)` модуля плагіна +- нативна поведінка середовища виконання походить із шляху `register(api)` модуля плагіна -Це розділення дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки для UI/схеми до того, як повноцінний час виконання стане активним. +Такий поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки для UI/схем до повної активації середовища виконання. ### Плагіни каналів і спільний інструмент повідомлень -Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для -звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у ядрі, а -плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. +Плагінам каналів не потрібно реєструвати окремий інструмент надсилання/редагування/реакцій для +звичайних дій чату. OpenClaw зберігає один спільний інструмент `message` у ядрі, а +плагіни каналів володіють специфічними для каналу виявленням і виконанням за ним. Поточна межа така: -- ядро володіє хостом спільного інструмента `message`, wiring для prompt, веденням - обліку сесій/гілок та диспетчеризацією виконання -- плагіни каналів володіють виявленням дій в обмеженому контексті, виявленням можливостей і будь-якими +- ядро володіє спільним хостом інструмента `message`, прив’язкою до prompt, + обліком сесій/потоків і диспетчеризацією виконання +- плагіни каналів володіють виявленням дій у межах області, виявленням можливостей і будь-якими фрагментами схеми, специфічними для каналу -- плагіни каналів володіють граматикою розмов для сесій, специфічною для постачальника, наприклад тим, - як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов +- плагіни каналів володіють граматикою розмов сесії, специфічною для провайдера, наприклад + тим, як id розмов кодують id потоків або успадковуються від батьківських розмов - плагіни каналів виконують фінальну дію через свій адаптер дій -Для плагінів каналів поверхня SDK — це +Для плагінів каналів поверхнею SDK є `ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну повернути видимі дії, можливості та внески до схеми -разом, щоб ці частини не розходилися. +дозволяє плагіну разом повертати видимі дії, можливості та внески в схему, +щоб ці частини не розходилися між собою. -Ядро передає область часу виконання в цей крок виявлення. Важливі поля: +Ядро передає область виконання в цей крок виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -191,123 +190,121 @@ OpenClaw класифікує кожен завантажений плагін - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати -дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або -довіреної ідентичності запитувача, не хардкодячи специфічні для каналу гілки в -базовий інструмент `message`. +Це важливо для контекстно-залежних плагінів. Канал може приховувати або показувати +дії з повідомленнями залежно від активного облікового запису, поточної кімнати/потоку/повідомлення або +довіреної особи запитувача без жорстко закодованих гілок, специфічних для каналу, в +основному інструменті `message`. -Саме тому зміни маршрутизації embedded-runner і далі залишаються роботою плагіна: runner -відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб спільний -інструмент `message` відкривав правильну поверхню, що належить каналу, для поточного ходу. +Ось чому зміни маршрутизації embedded-runner усе ще залишаються роботою плагіна: виконавець +відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб +спільний інструмент `message` відкривав правильну поверхню, що належить каналу, для поточного ходу. -Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати середовище +Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають тримати середовище виконання всередині власних модулів розширення. Ядро більше не володіє середовищами -виконання дій повідомлень Discord, Slack, Telegram або WhatsApp під `src/agents/tools`. -Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані -плагіни мають імпортувати власний локальний код часу виконання безпосередньо зі своїх -модулів, що належать розширенню. +виконання дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані +плагіни мають імпортувати власний локальний код середовища виконання безпосередньо зі своїх +модулів розширення. -Та сама межа застосовується й до іменованих за постачальниками швів SDK загалом: ядро не має +Та сама межа застосовується до іменованих SDK-швів провайдерів загалом: ядро не повинно імпортувати зручні барелі, специфічні для каналів Slack, Discord, Signal, -WhatsApp чи подібних розширень. Якщо ядру потрібна певна поведінка, воно має або -використовувати власний барель `api.ts` / `runtime-api.ts` вбудованого плагіна, або -підняти потребу до вузької загальної можливості в спільному SDK. +WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, або споживайте +власний барель `api.ts` / `runtime-api.ts` вбудованого плагіна, або підвищуйте цю потребу +до вузької загальної можливості в спільному SDK. -Зокрема для опитувань існує два шляхи виконання: +Для опитувань зокрема існують два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну - модель опитування -- `actions.handleAction("poll")` — бажаний шлях для специфічної для каналу - семантики опитувань або додаткових параметрів опитування +- `outbound.sendPoll` — це спільний базовий шлях для каналів, що відповідають загальній + моделі опитувань +- `actions.handleAction("poll")` — бажаний шлях для семантики опитувань, специфічної для каналу, + або додаткових параметрів опитувань -Тепер ядро відкладає спільний розбір опитування до моменту, коли dispatch -опитування плагіна відхиляє дію, щоб обробники опитувань, що належать плагіну, могли приймати -специфічні для каналу поля опитування, не блокуючись спершу загальним парсером опитувань. +Тепер ядро відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна відхилить +дію, щоб обробники опитувань, що належать плагіну, могли приймати специфічні для каналу поля +опитувань без блокування загальним парсером опитувань раніше. -Повну послідовність запуску дивіться в [Конвеєр завантаження](#load-pipeline). +Повну послідовність запуску див. у [Конвеєр завантаження](#load-pipeline). ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір не пов’язаних інтеграцій. +**функції**, а не як мішок непов’язаних інтеграцій. Це означає: -- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії -- плагін функції зазвичай має володіти всією поверхнею функції, яку він додає -- канали мають споживати спільні можливості ядра замість того, щоб довільно повторно реалізовувати - поведінку постачальника +- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, пов’язаними з цією компанією +- плагін функції зазвичай має володіти повною поверхнею функції, яку він запроваджує +- канали мають споживати спільні можливості ядра замість того, щоб щоразу заново реалізовувати + поведінку провайдерів Приклади: -- вбудований плагін `openai` володіє поведінкою постачальника моделей OpenAI та поведінкою OpenAI - для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI, а також + поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень - вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs - вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft -- вбудований плагін `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google для - розуміння медіа + генерації зображень + вебпошуку -- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для отримання вебданих +- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також можливостями Google + для розуміння медіа + генерації зображень + вебпошуку +- вбудований плагін `firecrawl` володіє поведінкою отримання вебданих Firecrawl - вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми бекендами розуміння медіа -- вбудований плагін `qwen` володіє поведінкою текстового постачальника Qwen, а також - поведінкою розуміння медіа і генерації відео - плагін `voice-call` є плагіном функції: він володіє транспортом дзвінків, інструментами, - CLI, маршрутами й мостом медіапотоку Twilio, але споживає спільні можливості мовлення, - а також транскрипції та голосу в реальному часі замість прямого імпорту vendor-плагінів + CLI, маршрутами та мостом медіапотоку Twilio, але споживає спільні можливості мовлення, + а також транскрипції й голосу в реальному часі замість прямого імпорту плагінів постачальників Бажаний кінцевий стан: -- OpenAI знаходиться в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та +- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший вендор може робити те саме для власної області -- канали не мають перейматися тим, який vendor-плагін володіє постачальником; вони споживають - спільний контракт можливості, що відкривається ядром +- інший постачальник може робити те саме для власної області +- каналам байдуже, який плагін постачальника володіє провайдером; вони споживають + спільний контракт можливості, який надає ядро Ось ключова відмінність: -- **plugin** = межа володіння -- **capability** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів +- **плагін** = межа володіння +- **можливість** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів -Тому якщо OpenClaw додає нову сферу, наприклад відео, перше питання не -«який постачальник має хардкодити обробку відео?» Перше питання — «який -контракт можливості відео в ядрі?» Щойно такий контракт з’явиться, vendor-плагіни -зможуть реєструватися для нього, а плагіни каналів/функцій зможуть його споживати. +Тож якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не +«який провайдер має жорстко закодувати обробку відео?» Перше запитання таке: «який +базовий контракт можливості для відео?» Щойно такий контракт існує, плагіни постачальників +можуть реєструватися для нього, а плагіни каналів/функцій можуть його споживати. -Якщо можливості ще не існує, правильний крок зазвичай такий: +Якщо можливість ще не існує, правильний крок зазвичай такий: 1. визначити відсутню можливість у ядрі -2. відкрити її через API/час виконання плагіна у типізований спосіб -3. прив’язати канали/функції до цієї можливості -4. дозволити vendor-плагінам реєструвати реалізації +2. відкрити її через API/середовище виконання плагіна в типізованому вигляді +3. під’єднати канали/функції до цієї можливості +4. дозволити плагінам постачальників реєструвати реалізації -Це зберігає явне володіння й водночас уникає поведінки ядра, що залежить від -одного вендора або одноразового шляху коду, специфічного для плагіна. +Це зберігає явне володіння та водночас уникає поведінки ядра, яка залежить від +одного постачальника або окремого шляху коду, специфічного для одного плагіна. ### Шарування можливостей -Використовуйте цю ментальну модель, коли вирішуєте, де має належати код: +Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: -- **шар можливостей ядра**: спільна оркестрація, політики, fallback, правила - злиття конфігурації, семантика доставки та типізовані контракти -- **шар vendor-плагіна**: vendor-специфічні API, auth, каталоги моделей, синтез мовлення, - генерація зображень, майбутні відеобекенди, endpoints використання +- **базовий шар можливостей**: спільна оркестрація, політика, fallback, правила + об’єднання конфігурації, семантика доставки та типізовані контракти +- **шар плагіна постачальника**: API постачальника, автентифікація, каталоги моделей, синтез мовлення, + генерація зображень, майбутні відеобекенди, кінцеві точки використання - **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості ядра та подає їх на поверхню + яка споживає базові можливості та представляє їх на поверхні Наприклад, TTS має таку форму: -- ядро володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канали +- ядро володіє політикою TTS під час відповіді, порядком fallback, налаштуваннями та доставкою в канали - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний засіб часу виконання TTS для телефонії +- `voice-call` споживає допоміжний засіб середовища виконання TTS для телефонії -Той самий шаблон слід вважати бажаним і для майбутніх можливостей. +Ту саму модель слід віддавати перевагу й для майбутніх можливостей. -### Приклад багатоможливісного плагіна компанії +### Приклад плагіна компанії з кількома можливостями -Ззовні плагін компанії має виглядати цілісно. Якщо OpenClaw має спільні -контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, отримання вебданих і вебпошуку, -вендор може володіти всіма своїми поверхнями в одному місці: +Плагін компанії має виглядати цілісним ззовні. Якщо OpenClaw має спільні +контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння +медіа, генерації зображень, генерації відео, отримання вебданих і вебпошуку, +постачальник може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -361,13 +358,13 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви допоміжних функцій. Важлива форма: +Важливі не точні імена допоміжних засобів. Важлива форма: -- один плагін володіє поверхнею вендора -- ядро все ще володіє контрактами можливостей -- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора +- один плагін володіє поверхнею постачальника +- ядро все одно володіє контрактами можливостей +- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника - контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими - він заявляє, що володіє + стверджує, що володіє ### Приклад можливості: розуміння відео @@ -375,51 +372,51 @@ OpenClaw уже розглядає розуміння зображень/ауд можливість. Та сама модель володіння застосовується і тут: 1. ядро визначає контракт розуміння медіа -2. vendor-плагіни реєструють `describeImage`, `transcribeAudio` і - `describeVideo`, де це застосовно +2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` і + `describeVideo`, де це доречно 3. канали та плагіни функцій споживають спільну поведінку ядра замість - прямого прив’язування до коду вендора + прямого підключення до коду постачальника -Це не дає вбудовувати в ядро припущення одного постачальника щодо відео. Плагін володіє -поверхнею вендора; ядро володіє контрактом можливості та поведінкою fallback. +Це не дає вбудувати припущення одного провайдера щодо відео в ядро. Плагін володіє +поверхнею постачальника; ядро володіє контрактом можливості та поведінкою fallback. Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим -контрактом можливості та допоміжним засобом часу виконання, а vendor-плагіни -реєструють реалізації `api.registerVideoGenerationProvider(...)` для неї. +контрактом можливості та допоміжним засобом середовища виконання, а плагіни постачальників реєструють +реалізації `api.registerVideoGenerationProvider(...)` для неї. -Потрібен конкретний чекліст розгортання? Дивіться -[Посібник з можливостей](/uk/plugins/architecture). +Потрібен конкретний контрольний список упровадження? Див. +[Кулінарну книгу можливостей](/uk/plugins/architecture). -## Контракти та контроль +## Контракти та забезпечення дотримання Поверхня API плагінів навмисно типізована та централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -допоміжні засоби часу виконання, на які плагін може покладатися. +допоміжні засоби середовища виконання, на які може покладатися плагін. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт -- ядро може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють однаковий id постачальника -- під час запуску можна показувати придатну для дії діагностику для некоректної реєстрації -- контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати непомітному дрейфу +- ядро може відхиляти дублювання володіння, наприклад коли два плагіни реєструють той самий id провайдера +- під час запуску можна показувати діагностику для некоректної реєстрації, придатну до дій +- контрактні тести можуть забезпечувати володіння вбудованими плагінами та запобігати тихому дрейфу -Є два шари контролю: +Є два шари забезпечення дотримання: -1. **контроль реєстрації під час виконання** +1. **забезпечення дотримання під час реєстрації в середовищі виконання** Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: - дубльовані id постачальників, дубльовані id постачальників мовлення та некоректні + дублікати id провайдерів, дублікати id провайдерів мовлення та некоректні реєстрації породжують діагностику плагіна замість невизначеної поведінки. 2. **контрактні тести** - Вбудовані плагіни фіксуються в контрактних реєстрах під час тестів, щоб + Вбудовані плагіни фіксуються в реєстрах контрактів під час запусків тестів, щоб OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для - постачальників моделей, постачальників мовлення, постачальників вебпошуку та володіння - реєстраціями вбудованих плагінів. + провайдерів моделей, провайдерів мовлення, провайдерів вебпошуку та + володіння реєстрацією вбудованих компонентів. -Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою -поверхнею володіє. Це дозволяє ядру та каналам безшовно поєднуватися, бо -володіння оголошене, типізоване та тестоване, а не неявне. +Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін +володіє якою поверхнею. Це дозволяє ядру та каналам безшовно компонуватися, +оскільки володіння оголошене, типізоване та тестоване, а не неявне. -### Що має входити до контракту +### Що має належати до контракту Хороші контракти плагінів: @@ -427,68 +424,68 @@ OpenClaw уже розглядає розуміння зображень/ауд - малі - специфічні для можливості - належать ядру -- придатні для повторного використання кількома плагінами -- споживані каналами/функціями без знання про вендора +- повторно використовувані кількома плагінами +- придатні до споживання каналами/функціями без знання постачальника Погані контракти плагінів: -- vendor-специфічна політика, прихована в ядрі -- одноразові обхідні шляхи для плагінів, які оминають реєстр -- код каналу, який напряму звертається до реалізації вендора -- довільні об’єкти часу виконання, які не є частиною `OpenClawPluginApi` або +- політика постачальника, прихована в ядрі +- одноразові аварійні шляхи плагінів, що оминають реєстр +- код каналу, який напряму звертається до реалізації постачальника +- ad hoc об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім +Якщо є сумніви, підніміть рівень абстракції: спочатку визначте можливість, а потім дозвольте плагінам підключатися до неї. ## Модель виконання -Нативні плагіни OpenClaw працюють **усередині процесу** разом із Gateway. Вони не -ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й -код ядра. +Нативні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не +ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що +й код ядра. Наслідки: -- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та служби -- помилка в нативному плагіні може призвести до збою або дестабілізації gateway +- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси +- помилка нативного плагіна може аварійно завершити роботу або дестабілізувати gateway - зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні пакети безпечніші за замовчуванням, оскільки наразі OpenClaw розглядає їх -як пакети метаданих/контенту. У поточних випусках це переважно означає -вбудовані Skills. +Сумісні пакети безпечніші за замовчуванням, тому що OpenClaw наразі розглядає їх +як пакети метаданих/вмісту. У поточних релізах це переважно означає вбудовані +Skills. -Для не вбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте -workspace-плагіни як код для етапу розробки, а не як виробниче значення за замовчуванням. +Використовуйте allowlist і явні шляхи встановлення/завантаження для невбудованих плагінів. Розглядайте +плагіни робочого простору як код для етапу розробки, а не як виробничі значення за замовчуванням. -Для назв пакетів у вбудованому workspace зберігайте id плагіна прив’язаним до npm-імені: -`@openclaw/` за замовчуванням, або затверджений типізований суфікс, такий як +Для імен пакетів вбудованого робочого простору зберігайте прив’язку id плагіна до npm- +імені: `@openclaw/` за замовчуванням або затверджений типізований суфікс, як-от `-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли пакет навмисно відкриває вужчу роль плагіна. Важлива примітка щодо довіри: - `plugins.allow` довіряє **id плагінів**, а не походженню джерела. -- Workspace-плагін із тим самим id, що й вбудований плагін, навмисно затіняє - вбудовану копію, коли такий workspace-плагін увімкнено/додано до allowlist. +- Плагін робочого простору з тим самим id, що й у вбудованого плагіна, навмисно затіняє + вбудовану копію, коли такий плагін робочого простору увімкнено/дозволено в allowlist. - Це нормально й корисно для локальної розробки, тестування патчів і хотфіксів. ## Межа експорту -OpenClaw експортує можливості, а не зручні реалізації. +OpenClaw експортує можливості, а не зручності реалізації. -Зберігайте реєстрацію можливостей публічною. Обрізайте експорти допоміжних засобів, які не є контрактами: +Зберігайте реєстрацію можливостей публічною. Скорочуйте допоміжні експорти, що не є контрактами: - підшляхи допоміжних засобів, специфічних для вбудованих плагінів -- підшляхи plumbing часу виконання, не призначені як публічний API -- vendor-специфічні зручні допоміжні засоби -- допоміжні засоби setup/onboarding, які є деталями реалізації +- підшляхи внутрішньої логістики середовища виконання, не призначені як публічний API +- вендор-специфічні допоміжні засоби +- допоміжні засоби налаштування/онбордингу, які є деталями реалізації -Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в -згенерованій карті експортів SDK задля сумісності та підтримки вбудованих плагінів. -Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для +Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в згенерованій карті +експорту SDK заради сумісності та підтримки вбудованих плагінів. Поточні приклади включають +`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Вважайте їх +зарезервованими експортами деталей реалізації, а не рекомендованим шаблоном SDK для нових сторонніх плагінів. ## Конвеєр завантаження @@ -500,83 +497,84 @@ OpenClaw експортує можливості, а не зручні реал 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає стан увімкнення для кожного кандидата -6. завантажує увімкнені нативні модулі через jiti -7. викликає хуки нативних `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів -8. відкриває реєстр для команд/поверхонь часу виконання +5. вирішує, чи має бути ввімкнений кожен кандидат +6. завантажує ввімкнені нативні модулі через jiti +7. викликає хуки `register(api)` нативного плагіна (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів +8. відкриває реєстр для поверхонь команд/середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає наявний варіант (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання часу виконання. Кандидати блокуються, -коли entrypoint виходить за межі кореня плагіна, шлях є доступним для запису всім, або -володіння шляхом виглядає підозріло для не вбудованих плагінів. +Перевірки безпеки відбуваються **до** виконання коду середовища виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня плагіна, шлях доступний для запису всім, або +власність шляху виглядає підозріло для невбудованих плагінів. -### Поведінка «спочатку маніфест» +### Поведінка на основі маніфесту -Маніфест — це джерело істини control-plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: - ідентифікувати плагін - виявляти оголошені канали/Skills/схему конфігурації або можливості пакета - перевіряти `plugins.entries..config` -- доповнювати мітки/плейсхолдери Control UI +- доповнювати мітки/заповнювачі Control UI - показувати метадані встановлення/каталогу -Для нативних плагінів модуль часу виконання є частиною data-plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки постачальників. +Для нативних плагінів модуль середовища виконання є частиною data plane. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. ### Що кешує завантажувач -OpenClaw зберігає короткі внутрішньопроцесні кеші для: +OpenClaw зберігає короткоживучі кеші в межах процесу для: - результатів виявлення - даних реєстру маніфестів - завантажених реєстрів плагінів -Ці кеші зменшують стрибкоподібні витрати запуску та повторних команд. Їх безпечно -сприймати як короткоживучі кеші продуктивності, а не як постійне сховище. +Ці кеші зменшують пікові витрати під час запуску та повторних команд. Їх безпечно +розглядати як короткоживучі кеші продуктивності, а не як постійне зберігання. Примітка щодо продуктивності: -- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешування через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені плагіни не змінюють напряму довільні глобальні об’єкти ядра. Вони +Завантажені плагіни не змінюють напряму випадкові глобальні змінні ядра. Вони реєструються в центральному реєстрі плагінів. Реєстр відстежує: -- записи плагінів (ідентичність, джерело, походження, стан, діагностика) +- записи плагінів (ідентичність, джерело, походження, статус, діагностика) - інструменти -- застарілі хуки й типізовані хуки +- застарілі хуки та типізовані хуки - канали -- постачальників -- обробники gateway RPC +- провайдери +- обробники Gateway RPC - HTTP-маршрути - реєстратори CLI -- фонові служби -- команди, що належать плагінам +- фонові сервіси +- команди, що належать плагіну -Потім функції ядра читають із цього реєстру, а не звертаються безпосередньо до модулів плагінів. -Це зберігає односторонність завантаження: +Потім можливості ядра читають цей реєстр замість прямої взаємодії з модулями плагінів. +Це зберігає одностороннє завантаження: - модуль плагіна -> реєстрація в реєстрі -- час виконання ядра -> споживання реєстру +- середовище виконання ядра -> споживання реєстру -Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «читати реєстр», а не «додавати окремі випадки для кожного модуля плагіна». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра +потрібна лише одна точка інтеграції: «прочитати реєстр», а не «робити спеціальний випадок для кожного +модуля плагіна». -## Колбеки прив’язки розмов +## Зворотні виклики прив’язки розмови -Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. +Плагіни, які прив’язують розмову, можуть реагувати на завершення погодження. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як -запит на прив’язку схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, +як запит на прив’язку схвалено або відхилено: ```ts export default { @@ -596,29 +594,29 @@ export default { }; ``` -Поля payload callback: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` - `binding`: визначена прив’язка для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та +- `request`: початкове резюме запиту, підказка від’єднання, id відправника та метадані розмови -Цей callback призначений лише для сповіщення. Він не змінює того, хто має право -прив’язувати розмову, і виконується після завершення обробки схвалення ядром. +Цей зворотний виклик використовується лише для сповіщення. Він не змінює того, хто має право +прив’язувати розмову, і запускається після завершення обробки погодження в ядрі. -## Хуки часу виконання постачальника +## Хуки середовища виконання провайдера -Тепер плагіни постачальників мають два шари: +Тепер плагіни провайдерів мають два шари: -- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до - завантаження часу виконання, а також `providerAuthChoices` для дешевих міток onboarding/auth-choice - і метаданих прапорців CLI до завантаження часу виконання -- хуки часу конфігурації: `catalog` / застарілий `discovery`, а також `applyConfigDefaults` -- хуки часу виконання: `normalizeModelId`, `normalizeTransport`, +- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації до + завантаження середовища виконання, а також `providerAuthChoices` для дешевих міток + онбордингу/вибору автентифікації та метаданих прапорців CLI до завантаження середовища виконання +- хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- хуки середовища виконання: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, - `resolveSyntheticAuth`, `resolveExternalOAuthProfiles`, + `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, `shouldDeferSyntheticProfileAuth`, `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `contributeResolvedModelCompat`, `capabilities`, @@ -635,84 +633,84 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскрипту та -політикою інструментів. Ці хуки — поверхня розширення для поведінки постачальника без +OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, без потреби в цілком власному транспорті висновку. -Використовуйте `providerAuthEnvVars` у маніфесті, коли постачальник має облікові дані на основі env, -які мають бачити загальні шляхи auth/status/model-picker без завантаження -часу виконання плагіна. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні -CLI onboarding/auth-choice повинні знати id вибору постачальника, мітки груп і просту -однопрапорцеву auth-прив’язку без завантаження часу виконання постачальника. Зберігайте `envVars` -часу виконання постачальника для підказок, орієнтованих на оператора, таких як мітки onboarding або +Використовуйте маніфестний `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, +які загальні шляхи автентифікації/статусу/вибору моделі мають бачити без завантаження середовища виконання плагіна. +Використовуйте маніфестний `providerAuthChoices`, коли поверхні CLI для онбордингу/вибору автентифікації +мають знати id вибору провайдера, мітки груп і просту +логіку автентифікації одним прапорцем без завантаження середовища виконання провайдера. Залишайте +`envVars` середовища виконання провайдера для підказок для оператора, таких як мітки онбордингу або змінні налаштування OAuth client-id/client-secret. -### Порядок хуків і використання +### Порядок і використання хуків -Для плагінів моделей/постачальників OpenClaw викликає хуки приблизно в такому порядку. +Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. Стовпець «Коли використовувати» — це швидкий посібник для вибору. -| # | Хук | Що він робить | Коли використовувати | -| --- | -------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або значеннями base URL за замовчуванням | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей постачальника | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(це не хук плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id до пошуку | Постачальник володіє очищенням псевдонімів до канонічного визначення моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника до загального збирання моделі | Постачальник володіє очищенням транспорту для користувацьких id постачальників у тому самому сімействі транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення часу виконання/постачальника | Постачальнику потрібно очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігураційних постачальників | Постачальнику потрібні виправлення метаданих native streaming usage, що залежать від endpoint | -| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для конфігураційних постачальників до завантаження runtime auth | Постачальник має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований визначник AWS env-marker | -| 8 | `resolveSyntheticAuth` | Виводить локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Постачальник може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalOAuthProfiles` | Накладає зовнішні профілі OAuth; значення `persistence` за замовчуванням — `runtime-only` для облікових даних, що належать CLI/застосунку | Постачальник повторно використовує зовнішні облікові дані OAuth без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з auth на основі env/конфігурації | Постачальник зберігає синтетичні профілі-заповнювачі, які не мають перемагати за пріоритетом | -| 11 | `resolveDynamicModel` | Синхронний fallback для model id, що належать постачальнику, але ще не є в локальному реєстрі | Постачальник приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Постачальнику потрібні мережеві метадані до визначення невідомих id | -| 13 | `normalizeResolvedModel` | Фінальне переписування до того, як embedded runner використовує визначену модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Постачальник розпізнає власні моделі на proxy-транспортах, не перебираючи контроль над постачальником | -| 15 | `capabilities` | Метадані транскрипту/інструментарію, що належать постачальнику і використовуються спільною логікою ядра | Постачальнику потрібні особливості транскрипту/сімейства постачальника | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Постачальнику потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження про ключові слова, не навчаючи ядро правилам, специфічним для постачальника | -| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт reasoning-output | Постачальнику потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних обгорток параметрів потоку | Постачальнику потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного постачальника | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Постачальнику потрібен власний wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Постачальнику потрібні обгортки заголовків/тіла/сумісності моделі запиту без власного транспорту | -| 22 | `resolveTransportTurnState` | Додає native-заголовки або метадані транспорту для кожного ходу | Постачальник хоче, щоб загальні транспорти надсилали native-ідентичність ходу постачальника | -| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Постачальник хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику fallback | -| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` під час виконання | Постачальник зберігає додаткові auth-метадані й потребує користувацької форми токена часу виконання | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких endpoints оновлення або політики збоїв refresh | Постачальник не вписується в спільні refreshers `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли OAuth refresh завершується невдачею | Постачальнику потрібні власні вказівки з відновлення auth після збою refresh | -| 27 | `matchesContextOverflowError` | Визначник переповнення context window, що належить постачальнику | Постачальник має сирі помилки переповнення, які пропустили б загальні евристики | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить постачальнику | Постачальник може зіставити сирі помилки API/транспорту з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-постачальників | Постачальнику потрібне специфічне для proxy керування TTL кешу | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутньому auth | Постачальнику потрібна власна підказка відновлення при відсутньому auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Постачальнику потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Постачальнику потрібні синтетичні рядки forward-compat у `models list` і селекторах | -| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників binary-thinking | Постачальник відкриває лише двійкове thinking увімк./вимк. | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Постачальник хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Постачальник володіє політикою `/think` за замовчуванням для сімейства моделей | -| 36 | `isModernModelRef` | Визначник сучасної моделі для live-фільтрів профілів і вибору smoke | Постачальник володіє зіставленням бажаних live/smoke-моделей | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ часу виконання безпосередньо перед висновком | Постачальнику потрібен обмін токенів або короткоживучі облікові дані для запиту | -| 38 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та споріднених поверхонь статусу | Постачальнику потрібен користувацький парсинг токена usage/quota або інші облікові дані для usage | -| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника знімки usage/quota після визначення auth | Постачальнику потрібен специфічний для нього endpoint usage або парсер payload | -| 40 | `createEmbeddingProvider` | Будує адаптер embedding, що належить постачальнику, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати разом із плагіном постачальника | -| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для постачальника | Постачальнику потрібна користувацька політика транскрипту (наприклад, видалення thinking-блоків) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Постачальнику потрібні специфічні для нього переписування replay понад спільні допоміжні засоби компакції | -| 43 | `validateReplayTurns` | Фінальна валідація або переформування ходів replay перед embedded runner | Транспорт постачальника потребує суворішої валідації ходів після загальної санітизації | -| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або стан постачальника, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера | +| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не є хуком плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми id моделей до пошуку | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує сімейство `api` / `baseUrl` провайдера до загального складання моделі | Провайдер володіє очищенням транспорту для власних id провайдерів у тому ж сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує переписування сумісності native streaming-usage до конфігураційних провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage на основі кінцевої точки | +| 7 | `resolveConfigApiKey` | Визначає автентифікацію env-marker для конфігураційних провайдерів до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver | +| 8 | `resolveSyntheticAuth` | Виводить локальну/self-hosted або конфігураційну автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типовий `persistence` — `runtime-only` для облікових даних CLI/додатка | Провайдер повторно використовує облікові дані зовнішньої автентифікації без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених синтетичних заповнювачів профілю на користь автентифікації через env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний fallback для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані до визначення невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він і далі використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспорті, не перебираючи на себе роль провайдера | +| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схеми, що належить провайдеру, після нормалізації | Провайдер хоче мати попередження щодо ключових слів без додавання в ядро правил, специфічних для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає контракт native або tagged reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних обгорток опцій stream | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream власним транспортом | Провайдеру потрібен власний дротовий протокол, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/моделі запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає native-заголовки або метадані транспорту для конкретного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу, специфічну для провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику fallback | +| 24 | `formatApiKey` | Форматувач профілю автентифікації: збережений профіль стає рядком `apiKey` для середовища виконання | Провайдер зберігає додаткові метадані автентифікації й потребує власної форми токена середовища виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних refresh endpoint або політики помилок оновлення | Провайдер не відповідає спільним механізмам оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка відновлення, що додається при збої оновлення OAuth | Провайдеру потрібні власні вказівки з відновлення автентифікації після збою оновлення | +| 27 | `matchesContextOverflowError` | Матчер переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не виявляють | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відсутню автентифікацію | Провайдеру потрібна підказка відновлення після відсутності автентифікації, специфічна для провайдера | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховувати застарілі upstream-записи або замінювати їх підказкою постачальника | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні записи каталогу, додані після виявлення | Провайдеру потрібні синтетичні записи для прямої сумісності в майбутньому в `models list` і вибирачах | +| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер надає лише двійковий режим thinking увімк./вимк. | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | +| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 36 | `isModernModelRef` | Матчер modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед висновком | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту | +| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання | +| 39 | `fetchUsageSnapshot` | Отримує й нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна власна endpoint використання або парсер корисного навантаження | +| 40 | `createEmbeddingProvider` | Будує адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати разом із плагіном провайдера | +| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) | +| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні власні переписування replay понад спільні допоміжні засоби ущільнення | +| 43 | `validateReplayTurns` | Остаточна валідація або зміна форми ходів replay перед embedded runner | Транспорту провайдера потрібна суворіша валідація ходів після загальної санітизації | +| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан провайдера, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний плагін постачальника, а потім переходять до інших плагінів постачальників, здатних обробляти хуки, -доки якийсь із них справді не змінить id моделі або транспорт/конфігурацію. Це -дає змогу працювати shim-постачальникам для псевдонімів/сумісності без вимоги, щоб викликач знав, -який вбудований плагін володіє переписуванням. Якщо жоден хук постачальника не перепише -підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google -усе одно застосує це очищення сумісності. +плагін провайдера, що відповідає, а потім переходять до інших плагінів провайдерів, здатних до хуків, +поки хтось із них фактично не змінить id моделі або транспорт/конфігурацію. Це зберігає +роботу shim-провайдерів alias/compat без вимоги до викликача знати, який +вбудований плагін володіє переписуванням. Якщо жоден хук провайдера не перепише підтримуваний +запис конфігурації сімейства Google, усе одно застосовується нормалізатор конфігурації вбудованого Google +для цього очищення сумісності. -Якщо постачальнику потрібен повністю користувацький wire protocol або користувацький виконавець запитів, -це вже інший клас розширення. Ці хуки призначені для поведінки постачальника, -яка все ще працює на звичайному циклі висновку OpenClaw. +Якщо провайдеру потрібен повністю власний дротовий протокол або власний виконавець запитів, +це інший клас розширення. Ці хуки призначені для поведінки провайдера, яка +все ще працює на звичайному циклі висновку OpenClaw. -### Приклад постачальника +### Приклад провайдера ```ts api.registerProvider({ @@ -770,111 +768,114 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - і `wrapStreamFn`, тому що він володіє forward-compat для Claude 4.6, - підказками сімейства постачальника, вказівками з відновлення auth, інтеграцією - endpoint usage, придатністю prompt-cache, auth-aware значеннями конфігурації за замовчуванням, політикою - thinking за замовчуванням/адаптивного thinking для Claude та специфічним для Anthropic формуванням потоку для + `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` + і `wrapStreamFn`, тому що володіє прямою сумісністю Claude 4.6, + підказками сімейства провайдера, вказівками з відновлення автентифікації, інтеграцією + endpoint використання, придатністю prompt-cache, типовими значеннями конфігурації з урахуванням автентифікації, + політикою typical/adaptive thinking для Claude та специфічним для Anthropic формуванням stream для beta-заголовків, `/fast` / `serviceTier` і `context1m`. -- Допоміжні засоби потоку Anthropic, специфічні для Claude, поки що залишаються у - власному публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета +- Допоміжні засоби stream, специфічні для Claude в Anthropic, поки що залишаються у власному + публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі - конструктори обгорток Anthropic замість розширення загального SDK навколо правил - beta-заголовків одного постачальника. + побудовники обгорток Anthropic замість розширення загального SDK навколо правил beta-header одного + провайдера. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - тому що він володіє GPT-5.4 forward-compat, прямою нормалізацією OpenAI - `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приглушенням Spark, синтетичними рядками списку OpenAI та політикою thinking / - live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє - спільними native-обгортками OpenAI Responses для заголовків attribution, - `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex, - формування payload reasoning-compat і керування контекстом Responses. + тому що володіє прямою сумісністю GPT-5.4, нормалізацією прямого OpenAI + `openai-completions` -> `openai-responses`, підказками автентифікації з урахуванням Codex, + приховуванням Spark, синтетичними рядками списку OpenAI і політикою GPT-5 щодо thinking / + live-моделей; сімейство stream `openai-responses-defaults` володіє + спільними native-обгортками OpenAI Responses для заголовків атрибуції, + `/fast`/`serviceTier`, verbosity тексту, native Codex web search, + формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses. - OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, тому що цей постачальник є pass-through і може відкривати нові - model id до оновлення статичного каталогу OpenClaw; він також використовує - `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб - тримати специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і - політику prompt-cache поза ядром. Його політика replay походить від сімейства - `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` - володіє proxy-ін’єкцією reasoning і пропусками unsupported-model / `auto`. + `prepareDynamicModel`, оскільки провайдер є наскрізним і може відкривати нові + id моделей до оновлення статичного каталогу OpenClaw; він також використовує + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб утримувати + специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і + політику prompt-cache поза ядром. Його політика replay походить із сімейства + `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` + володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому - потрібні device login, що належить постачальнику, поведінка fallback моделей, особливості транскрипту Claude, - обмін токена GitHub на токен Copilot і endpoint usage, що належить постачальнику. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, + тому що йому потрібні login device, що належить провайдеру, поведінка fallback моделей, + особливості транскриптів Claude, обмін токена GitHub на токен Copilot і + endpoint використання, що належить провайдеру. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він - досі працює на основних транспортах OpenAI, але володіє нормалізацією - свого транспорту/base URL, політикою fallback оновлення OAuth, вибором транспорту за замовчуванням, - синтетичними рядками каталогу Codex і інтеграцією endpoint usage ChatGPT; він - використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. -- Google AI Studio та Gemini CLI OAuth використовують `resolveDynamicModel`, + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки + досі працює на базових транспортах OpenAI, але володіє нормалізацією + транспорту/base URL, політикою fallback для оновлення OAuth, типовим вибором транспорту, + синтетичними рядками каталогу Codex та інтеграцією endpoint використання ChatGPT; він + ділить те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI. +- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що - сімейство replay `google-gemini` володіє fallback сумісності вперед для Gemini 3.1, - native-валідацією replay Gemini, санітизацією bootstrap replay, tagged-режимом - reasoning-output і зіставленням сучасних моделей, тоді як - сімейство потоків `google-thinking` володіє нормалізацією payload thinking для Gemini; + сімейство replay `google-gemini` володіє fallback прямої сумісності Gemini 3.1, + native-валідацією replay Gemini, санітизацією bootstrap replay, режимом + tagged reasoning-output і зіставленням modern-model, тоді як + сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токенів, розбору токенів і - підключення endpoint quota. + `fetchUsageSnapshot` для форматування токенів, розбору токенів і підключення + endpoint квоти. - Anthropic Vertex використовує `buildReplayPolicy` через сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося - обмеженим id Claude, а не кожним транспортом `anthropic-messages`. + обмеженим id Claude, а не всім транспортом `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що він володіє + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, - для трафіку Anthropic-on-Bedrock; його політика replay все ще спирається на той самий + для трафіку Anthropic-on-Bedrock; його політика replay усе ще використовує той самий guard лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini - через сумісні з OpenAI транспорти та потребують санітизації - thought-signature Gemini без native-валідації replay Gemini або переписувань bootstrap. + через OpenAI-сумісні транспорти й потребують санітизації + thought-signature Gemini без native-валідації replay Gemini або + переписувань bootstrap. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один постачальник володіє і - семантикою повідомлень Anthropic, і OpenAI-сумісною семантикою; він зберігає видалення - thinking-блоків лише для Claude на стороні Anthropic, водночас перевизначаючи режим - reasoning output назад на native, а сімейство потоків `minimax-fast-mode` володіє - переписуванням моделей fast-mode на спільному шляху потоку. -- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він все ще використовує спільний - транспорт OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство потоків - `moonshot-thinking` відображає config плюс стан `/think` на свій - native двійковий payload thinking. + сімейство replay `hybrid-anthropic-openai`, тому що один провайдер володіє і + семантикою Anthropic-message, і OpenAI-compatible; він зберігає скидання + блоків thinking лише для Claude на боці Anthropic, водночас перевизначаючи режим + reasoning output назад на native, а сімейство stream `minimax-fast-mode` володіє + переписуваннями fast-mode на спільному шляху stream. +- Moonshot використовує `catalog`, а також `wrapStreamFn`, тому що все ще використовує спільний + транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; сімейство + stream `moonshot-thinking` зіставляє конфігурацію плюс стан `/think` на його + native binary thinking payload. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, що належать постачальнику, - нормалізація payload reasoning, підказки транскрипту Gemini і керування - TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію - thinking Kilo на спільному proxy-шляху потоку, водночас пропускаючи `kilo/auto` та - інші proxy model id, які не підтримують явні payload reasoning. + `isCacheTtlEligible`, тому що йому потрібні специфічні для провайдера заголовки запиту, + нормалізація payload reasoning, підказки для транскриптів Gemini та керування + TTL кешу Anthropic; сімейство stream `kilocode-thinking` зберігає ін’єкцію thinking Kilo + на спільному proxy stream path, водночас пропускаючи `kilo/auto` та + інші proxy id моделей, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він володіє fallback GLM-5, - значеннями `tool_stream` за замовчуванням, UX двійкового thinking, зіставленням сучасних моделей, - а також auth usage і отриманням quota; сімейство потоків `tool-stream-default-on` - не допускає винесення обгортки `tool_stream`, увімкненої за замовчуванням, у рукописну glue-логіку кожного постачальника. + `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback GLM-5, + типовими значеннями `tool_stream`, UX binary thinking, зіставленням modern-model + та і автентифікацією використання, і отриманням квоти; сімейство stream + `tool-stream-default-on` утримує обгортку `tool_stream`, увімкнену за замовчуванням, поза + написаною вручну склейкою для кожного провайдера. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - тому що він володіє нормалізацією native-транспорту xAI Responses, переписуваннями - псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / - reasoning-payload, повторним використанням fallback auth для інструментів, що належать плагіну, - визначенням моделей Grok із forward-compat та compat-патчами, що належать постачальнику, - такими як профіль схем інструментів xAI, непідтримувані ключові слова схеми, native `web_search` і декодування аргументів виклику інструментів із HTML-entities. + тому що володіє нормалізацією native xAI Responses transport, переписуванням псевдонімів fast-mode для Grok, + типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для інструментів, що належать плагіну, прямим визначенням + моделей Grok та патчами compat, що належать провайдеру, такими як профіль схеми інструментів xAI, + непідтримувані ключові слова схеми, native `web_search` і декодування аргументів виклику інструментів із HTML-сутностей. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - тримати особливості транскрипту/інструментарію поза ядром. -- Вбудовані постачальники лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, + утримувати особливості транскриптів/інструментів поза ядром. +- Вбудовані провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації +- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації розуміння медіа й генерації відео для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, тому що їхня поведінка - `/usage` належить плагіну, навіть якщо висновок і далі проходить через спільні транспорти. +- MiniMax і Xiaomi використовують `catalog`, а також хуки використання, оскільки їхня поведінка + `/usage` належить плагіну, хоча сам висновок і далі працює через спільні транспорти. -## Допоміжні засоби часу виконання +## Допоміжні засоби середовища виконання Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: @@ -897,14 +898,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію ядра `messages.tts` і вибір постачальника. -- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни повинні ресемплювати/кодувати для постачальників. -- `listVoices` є необов’язковим для кожного постачальника. Використовуйте це для голосових селекторів або потоків setup, що належать вендору. -- Переліки голосів можуть містити багатші метадані, такі як локаль, стать і теги особистості для селекторів, обізнаних про постачальника. +- `textToSpeech` повертає звичайний payload TTS ядра для поверхонь файлів/голосових повідомлень. +- Використовує базову конфігурацію `messages.tts` і вибір провайдера. +- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни повинні ресемплювати/кодувати для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосів або потоків налаштування, що належать постачальнику. +- Списки голосів можуть включати багатші метадані, такі як локаль, стать і теги особистості для вибирачів, обізнаних про провайдера. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -924,15 +925,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповіді в ядрі. -- Використовуйте постачальників мовлення для поведінки синтезу, що належить вендору. -- Застарілий ввід Microsoft `edge` нормалізується до id постачальника `microsoft`. -- Бажана модель володіння є орієнтованою на компанію: один vendor-плагін може володіти - текстовими, мовленнєвими, графічними та майбутніми медіапостачальниками, у міру того як OpenClaw додає - контракти цих можливостей. +- Зберігайте політику TTS, fallback і доставку відповідей у ядрі. +- Використовуйте провайдери мовлення для поведінки синтезу, що належить постачальнику. +- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один плагін постачальника може + володіти текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додає відповідні + контракти можливостей. -Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого -постачальника media-understanding замість загального мішка ключ/значення: +Для розуміння зображень/аудіо/відео плагіни реєструють один типізований +провайдер розуміння медіа замість загального мішка ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -946,16 +947,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, конфігурацію та wiring каналів у ядрі. -- Зберігайте поведінку вендора в плагіні постачальника. +- Зберігайте оркестрацію, fallback, конфігурацію та підключення каналів у ядрі. +- Зберігайте поведінку постачальника в плагіні провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується того ж шаблону: - - ядро володіє контрактом можливості та допоміжним засобом часу виконання - - vendor-плагіни реєструють `api.registerVideoGenerationProvider(...)` +- Генерація відео вже дотримується того самого шаблону: + - ядро володіє контрактом можливості та допоміжним засобом середовища виконання + - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)` - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів часу виконання media-understanding плагіни можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -970,8 +971,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо плагіни можуть використовувати або час виконання media-understanding, -або старіший псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або середовище виконання +розуміння медіа, або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -984,13 +985,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для +- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) та порядок fallback постачальників. -- Повертає `{ text: undefined }`, коли не отримано виходу транскрипції (наприклад, вхід пропущено/не підтримується). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. +- Використовує базову конфігурацію аудіо для розуміння медіа (`tools.media.audio`) і порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли вихід транскрипції не створюється (наприклад, якщо вхід пропущено або не підтримується). +- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. -Плагіни також можуть запускати фонові підзапуски subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові запуски підлеглих агентів через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1006,12 +1007,12 @@ const result = await api.runtime.subagent.run({ - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для резервних запусків, що належать плагіну, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Для fallback-запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. - Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски subagent недовірених плагінів і далі працюють, але запити на перевизначення відхиляються замість тихого fallback. +- Запуски підлеглих агентів із недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються, а не тихо переводяться в fallback. -Для вебпошуку плагіни можуть споживати спільний допоміжний засіб часу виконання замість -звернення до wiring інструмента агента: +Для вебпошуку плагіни можуть споживати спільний допоміжний засіб середовища виконання замість +проникнення в логіку інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1027,13 +1028,13 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати постачальників вебпошуку через +Плагіни також можуть реєструвати провайдерів вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір постачальника, визначення облікових даних і спільну семантику запитів у ядрі. -- Використовуйте постачальників вебпошуку для vendor-специфічних транспортів пошуку. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдери вебпошуку для транспортів пошуку, специфічних для постачальника. - `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1049,12 +1050,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка постачальників генерації зображень. -- `listProviders(...)`: перелічити доступних постачальників генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. +- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. ## HTTP-маршрути Gateway -Плагіни можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP-endpoint-и через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1072,30 +1073,30 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"` для вимоги звичайного auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує плагін. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. -- `handler`: повертайте `true`, коли маршрут обробив запит. +- `auth`: обов’язково. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки webhook, керованої плагіном. +- `match`: необов’язково. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язково. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `handler`: повертає `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено й воно спричинить помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. - Маршрути плагінів повинні явно оголошувати `auth`. -- Конфлікти однакового `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області часу виконання оператора. Вони призначені для webhook/перевірки підпису, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах області часу виконання запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області часу виконання маршруту плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з ідентичністю, область часу виконання повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- Конфлікти точного `path + match` відхиляються, якщо не встановлено `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` мають бути лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime scope. Вони призначені для webhook/перевірки підпису, керованих плагіном, а не для привілейованих викликів допоміжних засобів Gateway. +- Маршрути `auth: "gateway"` працюють у межах runtime scope запиту Gateway, але ця область навмисно консервативна: + - bearer-автентифікація через shared secret (`gateway.auth.mode = "token"` / `"password"`) фіксує runtime scope маршрутів плагінів на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів плагінів з ідентичністю, runtime scope повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth автоматично є admin-поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим автентифікації з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту SDK плагінів -Під час авторингу плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час створення плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: - `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. -- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. +- `openclaw/plugin-sdk/core` для загального спільного контракту з боку плагіна. - `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`). - Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, @@ -1110,14 +1111,14 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного wiring setup/auth/reply/webhook. - `channel-inbound` — це спільний дім для debounce, зіставлення згадок, - форматування envelope і допоміжних засобів контексту вхідного envelope. - `channel-setup` — це вузький шов setup для необов’язкового встановлення. - `setup-runtime` — це безпечна для часу виконання поверхня setup, яку використовують `setupEntry` / - відкладений запуск, включно з безпечними для імпорту patch-адаптерами setup. - `setup-adapter-runtime` — це шов адаптера setup облікового запису з урахуванням env. - `setup-tools` — це малий шов допоміжних засобів CLI/архіву/документації (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` для спільної логіки налаштування/автентифікації/відповідей/webhook. + `channel-inbound` — це спільне місце для debounce, зіставлення згадок, + форматування envelope та допоміжних засобів контексту вхідного envelope. + `channel-setup` — це вузький шов налаштування необов’язкового встановлення. + `setup-runtime` — це безпечна для runtime поверхня налаштування, що використовується `setupEntry` / + відкладеним запуском, включно з безпечними для імпорту адаптерами patch налаштування. + `setup-adapter-runtime` — це шов адаптера налаштування облікового запису, обізнаний про env. + `setup-tools` — це малий шов допоміжних засобів CLI/архівів/документації (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, @@ -1135,191 +1136,188 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів часу виконання/конфігурації. - `telegram-command-config` — це вузький публічний шов для нормалізації/валідації користувацьких - команд Telegram і він залишається доступним, навіть якщо поверхня контракту вбудованого + `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації власних + команд Telegram і залишається доступним, навіть якщо поверхня контракту вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний шов тексту/markdown/логування, включно з - видаленням видимого для асистента тексту, допоміжними засобами рендерингу/розбиття markdown, засобами редагування, - допоміжними засобами тегів директив і утилітами безпечного тексту. -- Шви каналів, специфічні для схвалення, мають віддавати перевагу одному контракту `approvalCapability` - на плагіні. Потім ядро читає auth, доставку, рендеринг і - native-маршрутизацію схвалення через цю одну можливість замість змішування - поведінки схвалення з не пов’язаними полями плагіна. + `text-runtime` — це спільний шов для тексту/markdown/логування, включно з + видаленням видимого асистенту тексту, допоміжними засобами рендерингу/розбиття markdown, засобами редагування, + допоміжними засобами тегів директив і безпечними текстовими утилітами. +- Для channel seam, пов’язаних із погодженнями, слід віддавати перевагу одному контракту + `approvalCapability` на плагіні. Потім ядро читає автентифікацію погоджень, доставку, рендеринг і + поведінку native routing через цю одну можливість замість змішування + поведінки погоджень у нерелевантні поля плагіна. - `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як - shim сумісності для старіших плагінів. Новий код має імпортувати натомість вужчі - загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього shim. -- Внутрішні механізми вбудованих розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати - публічні entrypoint репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` і вузько обмежені файли, такі як - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра чи з + shim сумісності для старіших плагінів. Новий код має імпортувати вужчі + загальні примітиви, а код репозиторію не повинен додавати нові імпорти shim. +- Внутрішні частини вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати публічні точки входу репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js`, і вузько спрямовані файли, такі як + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з іншого розширення. -- Розділення entrypoint у репозиторії: +- Поділ точок входу репозиторію: `/api.js` — це барель допоміжних засобів/типів, - `/runtime-api.js` — це барель лише для часу виконання, - `/index.js` — це entrypoint вбудованого плагіна, - а `/setup-entry.js` — це entrypoint setup-плагіна. -- Поточні приклади вбудованих постачальників: - - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких - як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`. - - OpenAI використовує `api.js` для конструкторів постачальників, допоміжних засобів моделей за замовчуванням і - конструкторів realtime-постачальників. - - OpenRouter використовує `api.js` для свого конструктора постачальника плюс допоміжні - засоби onboarding/config, тоді як `register.runtime.js` усе ще може повторно експортувати загальні + `/runtime-api.js` — барель лише для runtime, + `/index.js` — точка входу вбудованого плагіна, + а `/setup-entry.js` — точка входу плагіна налаштування. +- Поточні приклади вбудованих провайдерів: + - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів stream Claude, таких + як `wrapAnthropicProviderStream`, допоміжні засоби beta-header і розбір `service_tier`. + - OpenAI використовує `api.js` для побудовників провайдерів, допоміжних засобів типових моделей і + побудовників провайдерів реального часу. + - OpenRouter використовує `api.js` для свого побудовника провайдера та допоміжних засобів + онбордингу/конфігурації, тоді як `register.runtime.js` усе ще може повторно експортувати загальні допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні entrypoint, завантажені через фасад, віддають перевагу активному знімку конфігурації часу виконання, +- Публічні точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime, якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли - OpenClaw ще не віддає знімок часу виконання. + OpenClaw ще не обслуговує runtime snapshot. - Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір швів допоміжних засобів каналів під брендом вбудованих рішень усе ще - існує. Розглядайте їх як шви підтримки вбудованих/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти все одно мають потрапляти на - загальні підшляхи `plugin-sdk/*` або локальні барелі плагіна `api.js` / + зарезервований набір сумісності з brand-іменованими швами допоміжних засобів вбудованих каналів усе ще + існує. Розглядайте їх як шви для підтримки/сумісності вбудованих компонентів, а не як нові + цілі імпорту для сторонніх розробників; нові міжканальні контракти мають і далі + з’являтися в загальних підшляхах `plugin-sdk/*` або в локальних барелях плагіна `api.js` / `runtime-api.js`. Примітка щодо сумісності: -- Уникайте кореневого бареля `openclaw/plugin-sdk` у новому коді. -- Насамперед віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи - setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це бажаний контракт для нової роботи - з вбудованими та зовнішніми плагінами. - Розбір/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`. - Шлюзи дій повідомлень і допоміжні засоби id повідомлень реакцій мають належати +- Для нового коду уникайте кореневого бареля `openclaw/plugin-sdk`. +- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool є бажаним контрактом для нової роботи з + вбудованими та зовнішніми плагінами. + Розбір/зіставлення цілей належить до `openclaw/plugin-sdk/channel-targets`. + Обмеження дій повідомлень і допоміжні засоби id повідомлень для реакцій належать до `openclaw/plugin-sdk/channel-actions`. -- Барелі допоміжних засобів, специфічних для вбудованих розширень, не є стабільними за замовчуванням. Якщо +- Вбудовані барелі допоміжних засобів, специфічні для розширень, не є стабільними за замовчуванням. Якщо допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальним - швом `api.js` або `runtime-api.js` цього розширення замість просування до + швом `api.js` або `runtime-api.js` цього розширення замість винесення до `openclaw/plugin-sdk/`. -- Нові шви спільних допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір - цілей належить `openclaw/plugin-sdk/channel-targets`; специфічні для каналу - внутрішні механізми залишаються за локальним швом `api.js` або `runtime-api.js` - плагіна-власника. +- Нові шви спільних допоміжних засобів мають бути загальними, а не брендованими каналом. Спільний розбір + цілей належить до `openclaw/plugin-sdk/channel-targets`; внутрішні частини, специфічні для каналу, + залишаються за локальним швом `api.js` або `runtime-api.js` плагіна-власника. - Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують - їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є + їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є довгостроковим замороженим зовнішнім контрактом. ## Схеми інструмента повідомлень -Плагіни повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. -Тримайте поля, специфічні для постачальника, у плагіні, а не в спільному ядрі. +Плагіни мають володіти внесками до схем `describeMessageTool(...)`, специфічними для каналу. +Зберігайте поля, специфічні для провайдера, у плагіні, а не в спільному ядрі. Для спільних переносимих фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованого payload картки +- `createMessageToolCardSchema()` для структурованих payload карток -Якщо форма схеми має сенс лише для одного постачальника, визначайте її у власному -коді цього плагіна замість просування до спільного SDK. +Якщо форма схеми має сенс лише для одного провайдера, визначайте її у вихідному коді +цього плагіна замість просування в спільний SDK. ## Визначення цілей каналу -Плагіни каналів повинні володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -вихідний host узагальненим і використовуйте поверхню адаптера повідомлень для правил постачальника: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний хост узагальненим і використовуйте поверхню адаптера повідомлень для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль - трактувати як `direct`, `group` або `channel` до пошуку в каталозі. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - має вхід перейти одразу до визначення за схожістю з id замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли - ядру потрібне фінальне визначення, що належить постачальнику, після нормалізації або +- `messaging.inferTargetChatType({ to })` вирішує, чи слід розглядати нормалізовану ціль + як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи слід + відразу переходити до визначення за id-подібним значенням замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` є fallback плагіна, коли ядру + потрібне остаточне визначення, що належить провайдеру, після нормалізації або після промаху в каталозі. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, - специфічною для постачальника, після того як ціль визначено. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, специфічною для провайдера, щойно ціль визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають відбуватися до - пошуку peers/groups. -- Використовуйте `looksLikeId` для перевірок на кшталт «розглядати це як явний/native id цілі». -- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для постачальника, а не для - широкого пошуку в каталозі. -- Зберігайте native id постачальника, такі як chat id, thread id, JID, handle і room id, - усередині значень `target` або параметрів, специфічних для постачальника, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають ухвалюватися до + пошуку серед контактів/груп. +- Використовуйте `looksLikeId` для перевірок «розглядати це як явний/native id цілі». +- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для провайдера, а не для широкого пошуку в каталозі. +- Зберігайте native-id провайдера, такі як id чатів, id потоків, JID, handles та id кімнат, усередині + значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. ## Каталоги на основі конфігурації -Плагіни, які виводять записи каталогу з конфігурації, повинні тримати цю логіку в +Плагіни, які виводять записи каталогу з конфігурації, мають зберігати цю логіку в плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, такі як: +Використовуйте це, коли каналу потрібні контакти/групи на основі конфігурації, наприклад: -- DM-peers на основі allowlist -- налаштовані карти каналів/груп -- статичні fallback-каталоги в межах облікового запису +- контакти DM, визначені через allowlist +- налаштовані відповідності каналів/груп +- статичні fallback каталогу для конкретного облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: - фільтрацію запитів -- застосування обмежень +- застосування лімітів - дедуплікацію/нормалізацію - побудову `ChannelDirectoryEntry[]` -Специфічна для каналу перевірка облікового запису та нормалізація id мають залишатися в +Інспекція облікового запису та нормалізація id, специфічні для каналу, повинні залишатися в реалізації плагіна. -## Каталоги постачальників +## Каталоги провайдерів -Плагіни постачальників можуть визначати каталоги моделей для висновку через +Плагіни провайдерів можуть визначати каталоги моделей для висновку за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: -- `{ provider }` для одного запису постачальника -- `{ providers }` для кількох записів постачальників +- `{ provider }` для одного запису провайдера +- `{ providers }` для кількох записів провайдерів -Використовуйте `catalog`, коли плагін володіє model id, специфічними для постачальника, значеннями base URL -за замовчуванням або метаданими моделей, що залежать від auth. +Використовуйте `catalog`, коли плагін володіє id моделей, типовими значеннями base URL або +метаданими моделей, захищеними автентифікацією. -`catalog.order` керує тим, коли каталог плагіна зливається відносно -вбудованих неявних постачальників OpenClaw: +`catalog.order` визначає, коли каталог плагіна зливається відносно вбудованих +неявних провайдерів OpenClaw: -- `simple`: звичайні постачальники на основі API-ключа або env -- `profile`: постачальники, що з’являються, коли існують auth-профілі -- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників -- `late`: останній прохід, після інших неявних постачальників +- `simple`: прості провайдери на основі API-ключа або env +- `profile`: провайдери, що з’являються, коли існують профілі автентифікації +- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів +- `late`: останній прохід, після інших неявних провайдерів -Пізніші постачальники перемагають при колізії ключів, тож плагіни можуть навмисно -перевизначати вбудований запис постачальника з тим самим id постачальника. +Пізніші провайдери перемагають у разі колізії ключів, тож плагіни можуть навмисно +перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` усе ще працює як застарілий псевдонім -- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` +- `discovery` все ще працює як застарілий псевдонім +- якщо зареєстровані і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Канальне інспектування лише для читання +## Канальна інспекція лише для читання -Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації +Якщо ваш плагін реєструє канал, бажано реалізувати `plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях часу виконання. Він може припускати, що облікові дані - повністю матеріалізовані, і може швидко завершуватися помилкою, коли потрібні секрети відсутні. +- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config - repair, не повинні вимагати матеріалізації облікових даних часу виконання лише для + для відновлення, не повинні вимагати матеріалізації runtime-облікових даних лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/стану облікових даних, коли це доречно, наприклад: +- Включає поля джерела/статусу облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). -- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але - вони недоступні в поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність у режимі лише читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела) достатньо для команд на кшталт status. +- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але + недоступні в поточному шляху команди. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість збоїв або хибного повідомлення, що обліковий запис не налаштований. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштований. -## Package packs +## Пакети пакетів Каталог плагіна може містити `package.json` з `openclaw.extensions`: @@ -1333,60 +1331,59 @@ api.registerHttpRoute({ } ``` -Кожен запис стає плагіном. Якщо pack перелічує кілька розширень, id плагіна +Кожен запис стає плагіном. Якщо пакет містить кілька розширень, id плагіна стає `name/`. -Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб +Якщо ваш плагін імпортує залежності npm, встановіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` повинен залишатися в межах каталогу плагіна -після визначення symlink. Записи, що виходять за межі каталогу пакета, відхиляються. +Захисне правило безпеки: кожен запис `openclaw.extensions` повинен залишатися в межах каталогу плагіна +після розв’язання symlink. Записи, які виходять за межі каталогу пакета, +відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей під час виконання). Зберігайте дерева залежностей плагінів у стилі «чистий JS/TS» і уникайте пакетів, яким потрібні збірки `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle-скриптів і без dev dependencies під час runtime). Зберігайте дерева залежностей плагіна «чистими JS/TS» і уникайте пакетів, яким потрібні `postinstall`-збирання. -Необов’язково: `openclaw.setupEntry` може вказувати на легковаговий модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу, або -коли плагін каналу увімкнено, але він іще не налаштований, він завантажує `setupEntry` -замість повного entrypoint плагіна. Це робить запуск і setup легшими, -коли ваш основний entrypoint плагіна також прив’язує інструменти, хуки або інший код лише для часу виконання. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого плагіна каналу або +коли плагін каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry` +замість повної точки входу плагіна. Це робить запуск і налаштування легшими, +коли основна точка входу плагіна також підключає інструменти, хуки або інший код лише для runtime. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску gateway до початку прослуховування, навіть якщо канал уже налаштовано. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка повинна існувати -до того, як gateway почне слухати. На практиці це означає, що entrypoint setup -повинен реєструвати кожну можливість, що належить каналу, від якої залежить запуск, таку як: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати +до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування +повинна реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: -- сама реєстрація каналу -- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати -- будь-які методи gateway, інструменти або служби, які мають існувати в це саме вікно часу +- саму реєстрацію каналу +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти або сервіси, які мають існувати в це саме вікно -Якщо ваш повний entrypoint усе ще володіє будь-якою необхідною можливістю для запуску, не вмикайте -цей прапорець. Залиште плагін на типовій поведінці й дозвольте OpenClaw завантажити -повний entrypoint під час запуску. +Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте +цей прапорець. Дотримуйтеся типової поведінки й дозвольте OpenClaw завантажити +повну точку входу під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, до яких ядро -може звертатися до завантаження повного середовища виконання каналу. Поточна поверхня -просування setup така: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро +може консультуватися до завантаження повного runtime каналу. Поточна поверхня просування налаштування така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію -однокористувацького каналу в `channels..accounts.*` без завантаження повного entrypoint плагіна. -Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap до -іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно перевести застарілу конфігурацію каналу з одним +обліковим записом у `channels..accounts.*` без завантаження повної точки входу плагіна. +Matrix є поточним вбудованим прикладом: він переносить лише ключі автентифікації/завантаження +в іменований підвищений обліковий запис, коли іменовані облікові записи вже існують, і він може +зберігати налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці patch-адаптери setup зберігають ліниве виявлення поверхні контракту вбудованих рішень. -Час імпорту залишається малим; поверхня просування завантажується лише при першому використанні, замість повторного входу в запуск вбудованого каналу під час імпорту модуля. +Ці адаптери patch налаштування зберігають ледачим виявлення поверхні контракту вбудованих компонентів. Час імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають gateway RPC methods, тримайте їх на -префіксі, специфічному для плагіна. Простори імен адміністратора ядра (`config.*`, +Коли ці поверхні запуску включають методи gateway RPC, зберігайте їх на +префіксі, специфічному для плагіна. Простори імен admin ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються як `operator.admin`, навіть якщо плагін запитує вужчу область. @@ -1407,8 +1404,8 @@ Matrix — поточний вбудований приклад: він пере ### Метадані каталогу каналів -Плагіни каналів можуть рекламувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити дані каталогу. +Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. Приклад: @@ -1436,41 +1433,41 @@ Matrix — поточний вбудований приклад: він пере } ``` -Корисні поля `openclaw.channel` понад мінімальний приклад: +Корисні поля `openclaw.channel` поза мінімальним прикладом: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначення тексту посилання для посилання на документацію -- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має перевершувати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом на поверхні вибору -- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо вихідного форматування +- `docsLabel`: перевизначення тексту посилання на документацію +- `preferOver`: id плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом для поверхонь вибору +- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо форматування вихідних повідомлень - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних селекторів setup/configure, якщо встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документацією -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` -- `quickstartAllowFrom`: вмикає для каналу стандартний потік quickstart `allowFrom` +- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які досі приймаються для сумісності; віддавайте перевагу `exposure` +- `quickstartAllowFrom`: вмикає канал у стандартний потік quickstart `allowFrom` - `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку сесії під час визначення announce-target +- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку сесії під час визначення цілей анонсів -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Розмістіть JSON-файл в одному з таких місць: +OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). +Помістіть JSON-файл в одне з місць: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл повинен +один або кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Плагіни механізму контексту +## Плагіни контекстного рушія -Плагіни механізму контексту володіють оркестрацією контексту сесії для інжесту, збирання -та компакції. Реєструйте їх зі свого плагіна через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через +Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly +та compaction. Реєструйте їх зі свого плагіна через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. +конвеєр контексту, а не просто додати пошук у пам’яті або хуки. ```ts export default function (api) { @@ -1489,7 +1486,7 @@ export default function (api) { } ``` -Якщо ваш механізм **не** володіє алгоритмом компакції, залишайте `compact()` +Якщо ваш рушій **не** володіє алгоритмом compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1518,44 +1515,44 @@ export default function (api) { ## Додавання нової можливості Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний доступ усередину. Додайте відсутню можливість. +систему плагінів приватним проникненням усередину. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політикою, fallback, злиттям конфігурації, - життєвим циклом, семантикою для каналів і формою допоміжних засобів часу виконання. -2. додайте типізовані поверхні реєстрації/часу виконання плагіна +1. визначте базовий контракт + Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, об’єднання конфігурації, + життєвий цикл, семантика для каналів і форма допоміжних засобів середовища виконання. +2. додайте типізовані поверхні реєстрації/runtime для плагіна Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. прив’яжіть споживачів ядра + каналів/функцій - Канали та плагіни функцій повинні споживати нову можливість через ядро, - а не через прямий імпорт реалізації вендора. -4. зареєструйте реалізації вендора - Потім vendor-плагіни реєструють свої бекенди для цієї можливості. +3. під’єднайте споживачів у ядрі та каналах/функціях + Канали й плагіни функцій мають споживати нову можливість через ядро, + а не напряму імпортувати реалізацію постачальника. +4. зареєструйте реалізації постачальників + Потім плагіни постачальників реєструють свої бекенди для цієї можливості. 5. додайте контрактне покриття - Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. + Додайте тести, щоб володіння й форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається виразним, не стаючи хардкодженим під світогляд -одного постачальника. Дивіться [Посібник з можливостей](/uk/plugins/architecture), -щоб отримати конкретний чекліст файлів і готовий приклад. +Так OpenClaw зберігає власну позицію, не стаючи жорстко прив’язаним до +світогляду одного провайдера. Конкретний контрольний список файлів і робочий приклад див. +у [Кулінарній книзі можливостей](/uk/plugins/architecture). -### Чекліст можливості +### Контрольний список можливості Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися -цих поверхонь: +таких поверхонь: -- типи контракту ядра в `src//types.ts` -- runner/допоміжний засіб часу виконання ядра в `src//runtime.ts` +- типи базового контракту в `src//types.ts` +- базовий runner/допоміжний засіб runtime у `src//runtime.ts` - поверхня реєстрації API плагіна в `src/plugins/types.ts` -- wiring реєстру плагінів у `src/plugins/registry.ts` -- відкриття часу виконання плагіна в `src/plugins/runtime/*`, коли - плагіни функцій/каналів мають це споживати -- засоби фіксації/тестування в `src/test-utils/plugin-registration.ts` +- підключення реєстру плагінів у `src/plugins/registry.ts` +- відкриття runtime плагіна в `src/plugins/runtime/*`, коли + плагінам функцій/каналів потрібно це споживати +- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` - документація для операторів/плагінів у `docs/` -Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1595,6 +1592,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: - ядро володіє контрактом можливості + оркестрацією -- vendor-плагіни володіють реалізаціями вендора -- плагіни функцій/каналів споживають допоміжні засоби часу виконання +- плагіни постачальників володіють реалізаціями постачальників +- плагіни функцій/каналів споживають допоміжні засоби runtime - контрактні тести зберігають володіння явним