diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 1b1eb4f18..d111e2402 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,40 +1,41 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Ви хочете приклади конфігурацій або команд CLI для онбордингу постачальників моделей -summary: Огляд постачальників моделей із прикладами конфігурацій і потоками CLI + - Вам потрібні приклади конфігурацій або команди CLI для початкового налаштування постачальників моделей +summary: Огляд постачальників моделей із прикладами конфігурацій і потоків CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-08T03:42:18Z" + generated_at: "2026-04-08T18:10:02Z" model: gpt-5.4 provider: openai - source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 + source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b source_path: concepts/model-providers.md workflow: 15 --- # Постачальники моделей -На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). +Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених моделей. +- Якщо ви задаєте `agents.defaults.models`, воно стає списком дозволених моделей. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Резервні правила часу виконання, cooldown-перевірки та збереження перевизначень сеансу +- Резервні правила під час виконання, cooldown-перевірки та збереження перевизначень сеансу задокументовано в [/concepts/model-failover](/uk/concepts/model-failover). -- `models.providers.*.models[].contextWindow` — це власні метадані моделі; +- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання. -- Плагіни постачальників можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`; - OpenClaw об’єднує цей результат у `models.providers` перед записом +- Плагіни постачальників можуть додавати каталоги моделей через `registerProvider({ catalog })`; + OpenClaw об’єднує цей вивід у `models.providers` перед записом `models.json`. -- Маніфести постачальників можуть оголошувати `providerAuthEnvVars`, щоб загальні перевірки - автентифікації на основі змінних середовища не потребували завантаження часу виконання плагіна. Решта базової мапи змінних середовища - тепер використовується лише для неплагінових/базових постачальників і кількох випадків - загального пріоритету, як-от онбординг Anthropic із пріоритетом API-ключа. -- Плагіни постачальників також можуть володіти поведінкою часу виконання постачальника через +- Маніфести постачальників можуть оголошувати `providerAuthEnvVars` і + `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env і варіанти постачальників + не потребували завантаження runtime плагіна. Решта мапи env-змінних у ядрі тепер + потрібна лише для неплагінних/вбудованих постачальників і кількох випадків із загальним пріоритетом, + як-от початкове налаштування Anthropic із пріоритетом API-ключа. +- Плагіни постачальників також можуть володіти поведінкою runtime постачальника через `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -50,216 +51,219 @@ x-i18n: `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and + `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, і `onModelSelected`. -- Примітка: `capabilities` часу виконання постачальника — це спільні метадані раннера (сімейство постачальника, - особливості стенограми/інструментів, підказки щодо транспорту/кешу). Це не те - саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), - яка описує, що реєструє плагін (текстове інференсування, мовлення тощо). +- Примітка: `capabilities` runtime постачальника — це спільні метадані виконавця (сімейство постачальника, + особливості транскрипту/інструментів, підказки щодо транспорту/кешу). Це не те саме, + що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), + яка описує, що реєструє плагін (текстовий inference, мовлення тощо). -## Поведінка постачальника, що належить плагіну +## Поведінка постачальника, якою володіє плагін -Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає -загальний цикл інференсування. +Тепер плагіни постачальників можуть володіти більшістю специфічної логіки постачальника, тоді як OpenClaw зберігає +загальний цикл inference. -Типовий розподіл: +Типовий поділ: -- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу +- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками початкового налаштування/входу для `openclaw onboard`, `openclaw models auth` і безголового налаштування -- `wizard.setup` / `wizard.modelPicker`: постачальник володіє підписами вибору автентифікації, - застарілими псевдонімами, підказками списку дозволених моделей під час онбордингу та записами налаштування в засобах вибору онбордингу/моделей +- `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації, + застарілими псевдонімами, підказками щодо списку дозволених моделей для початкового налаштування і записами налаштування в пікерах онбордингу/моделей - `catalog`: постачальник з’являється в `models.providers` -- `normalizeModelId`: постачальник нормалізує застарілі/preview-ідентифікатори моделей перед +- `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед пошуком або канонізацією - `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту - перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника, + перед загальним збиранням моделі; OpenClaw спершу перевіряє відповідного постачальника, потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить транспорт -- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед - її використанням під час виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші +- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед тим, + як runtime її використає; OpenClaw спершу перевіряє відповідного постачальника, потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить конфігурацію. Якщо жоден - хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google - усе ще нормалізують підтримувані записи постачальників Google. -- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності власного потокового використання на основі кінцевої точки для конфігурованих постачальників -- `resolveConfigApiKey`: постачальник розв’язує автентифікацію за маркером змінної середовища для конфігурованих постачальників - без примусового повного завантаження автентифікації часу виконання. `amazon-bedrock` тут також має - вбудований резолвер маркерів середовища AWS, хоча автентифікація часу виконання Bedrock використовує - типовий ланцюжок AWS SDK. -- `resolveSyntheticAuth`: постачальник може надавати доступність локальної/self-hosted чи іншої - автентифікації на основі конфігурації без збереження незашифрованих секретів -- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні профілі-заповнювачі - як менш пріоритетні, ніж автентифікація на основі env/config + хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби для сімейства Google + усе одно нормалізують підтримувані записи постачальників Google. +- `applyNativeStreamingUsageCompat`: постачальник застосовує сумісні переписування native streaming-usage, керовані endpoint, для конфігурованих постачальників +- `resolveConfigApiKey`: постачальник визначає автентифікацію через env-маркери для конфігурованих постачальників + без примусового завантаження повної runtime-автентифікації. `amazon-bedrock` також має + вбудований resolver AWS env-marker тут, хоча runtime-автентифікація Bedrock використовує + стандартний ланцюжок AWS SDK. +- `resolveSyntheticAuth`: постачальник може показувати доступність локальної/self-hosted або іншої + автентифікації на основі конфігурації без збереження секретів у відкритому вигляді +- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні заповнювачі профілів + як менш пріоритетні, ніж автентифікація на основі env/конфігурації - `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному статичному каталозі -- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою - динамічного розв’язання +- `prepareDynamicModel`: постачальнику потрібно оновлення метаданих перед повторною спробою + динамічного визначення - `normalizeResolvedModel`: постачальнику потрібні переписування транспорту або base URL -- `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх - вендорних моделей навіть тоді, коли вони надходять через інший сумісний транспорт -- `capabilities`: постачальник публікує особливості стенограми/інструментів/сімейства постачальника -- `normalizeToolSchemas`: постачальник очищає схеми інструментів перед тим, як їх побачить - вбудований раннер -- `inspectToolSchemas`: постачальник показує попередження про схему, специфічні для транспорту, +- `contributeResolvedModelCompat`: постачальник додає прапори сумісності для своїх + вендорських моделей, навіть коли вони надходять через інший сумісний транспорт +- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальника +- `normalizeToolSchemas`: постачальник очищає схеми інструментів, перш ніж вбудований + виконавець їх побачить +- `inspectToolSchemas`: постачальник показує специфічні для транспорту попередження про схеми після нормалізації -- `resolveReasoningOutputMode`: постачальник вибирає власні чи теговані - контракти виводу міркувань -- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі -- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю - власним транспортом -- `wrapStreamFn`: постачальник застосовує обгортки сумісності заголовків/тіла/моделі запиту -- `resolveTransportTurnState`: постачальник надає власні заголовки або метадані транспорту - для кожного ходу -- `resolveWebSocketSessionPolicy`: постачальник надає власні заголовки сеансу WebSocket - або політику cooldown сеансу +- `resolveReasoningOutputMode`: постачальник обирає нативні чи теговані + контракти виводу reasoning +- `prepareExtraParams`: постачальник задає значення за замовчуванням або нормалізує параметри запиту для кожної моделі +- `createStreamFn`: постачальник замінює звичайний шлях потоку на повністю + власний транспорт +- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту +- `resolveTransportTurnState`: постачальник надає нативні заголовки транспорту + або метадані на кожен хід +- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket + або політику cool-down сесії - `createEmbeddingProvider`: постачальник володіє поведінкою embedding для пам’яті, коли вона - належить плагіну постачальника, а не базовому комутатору embedding -- `formatApiKey`: постачальник форматує збережені профілі автентифікації у - рядок `apiKey`, який очікує транспорт під час виконання + має належати плагіну постачальника, а не вбудованому комутатору embedding +- `formatApiKey`: постачальник форматує збережені профілі автентифікації у runtime-рядок + `apiKey`, очікуваний транспортом - `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних засобів оновлення `pi-ai` недостатньо - `buildAuthDoctorHint`: постачальник додає вказівки з відновлення, коли оновлення OAuth не вдається - `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника - помилки переповнення контекстного вікна, які пропустили б загальні евристики -- `classifyFailoverReason`: постачальник мапить специфічні для постачальника сирі помилки транспорту/API - на причини перемикання, як-от rate limit або перевантаження -- `isCacheTtlEligible`: постачальник визначає, які ідентифікатори моделей вищого рівня підтримують TTL кешу промптів + помилки переповнення context window, які загальні евристики пропустили б +- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки транспорту/API + з причинами failover, такими як rate limit або overload +- `isCacheTtlEligible`: постачальник вирішує, які upstream ідентифікатори моделей підтримують prompt-cache TTL - `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації - на специфічну для постачальника підказку з відновлення -- `suppressBuiltInModel`: постачальник приховує застарілі рядки вищого рівня і може повернути - помилку, що належить вендору, для прямих помилок розв’язання + специфічною для постачальника підказкою щодо відновлення +- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки і може повертати + помилку, яка належить вендору, для прямих збоїв визначення - `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після - виявлення та злиття конфігурації -- `isBinaryThinking`: постачальник володіє UX двійкового ввімкнення/вимкнення thinking + виявлення та об’єднання конфігурації +- `isBinaryThinking`: постачальник володіє UX бінарного thinking увімк./вимк. - `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей -- `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для +- `resolveDefaultThinkingLevel`: постачальник володіє політикою `/think` за замовчуванням для сімейства моделей -- `applyConfigDefaults`: постачальник застосовує специфічні глобальні типові значення постачальника +- `applyConfigDefaults`: постачальник застосовує глобальні значення за замовчуванням, специфічні для постачальника, під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей -- `isModernModelRef`: постачальник володіє зіставленням бажаної live/smoke-моделі +- `isModernModelRef`: постачальник володіє зіставленням бажаних live/smoke моделей - `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий - токен часу виконання -- `resolveUsageAuth`: постачальник розв’язує облікові дані використання/квоти для `/usage` + runtime-токен +- `resolveUsageAuth`: постачальник визначає облікові дані використання/квот для `/usage` і пов’язаних поверхонь статусу/звітності -- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором кінцевої точки використання, тоді як - базова система все ще володіє оболонкою підсумку та форматуванням -- `onModelSelected`: постачальник виконує побічні ефекти після вибору, як-от - телеметрія або ведення обліку сеансу, що належить постачальнику +- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором endpoint використання, тоді як + ядро все ще володіє оболонкою зведення та форматуванням +- `onModelSelected`: постачальник виконує побічні дії після вибору моделі, такі як + телеметрія або керування сеансом, що належить постачальнику Поточні вбудовані приклади: -- `anthropic`: резервна пряма сумісність для Claude 4.6, підказки з відновлення автентифікації, отримання - кінцевої точки використання, метадані TTL кешу/сімейства постачальника та глобальні - типові значення конфігурації з урахуванням автентифікації -- `amazon-bedrock`: зіставлення переповнення контексту та класифікація причин - перемикання, що належать постачальнику, для специфічних помилок Bedrock щодо throttle/not-ready, а також - спільне сімейство повторного відтворення `anthropic-by-model` для політики replay лише Claude +- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання + endpoint використання, метадані cache-TTL/сімейства постачальника та глобальні + значення конфігурації за замовчуванням з урахуванням автентифікації +- `amazon-bedrock`: визначення переповнення контексту та класифікація причин + failover для специфічних помилок Bedrock throttle/not-ready, а також + спільне сімейство повторного відтворення `anthropic-by-model` для захисту політики replay лише для Claude на трафіку Anthropic -- `anthropic-vertex`: обмеження політики replay лише Claude для Anthropic-message - трафіку -- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки - щодо можливостей постачальника, санітизація thought-signature Gemini на проксійованому трафіку Gemini, - проксійнe впровадження reasoning через сімейство потоків `openrouter-thinking`, переадресація - метаданих маршрутизації та політика TTL кешу -- `github-copilot`: онбординг/вхід із пристрою, резервне суміщення моделей для майбутньої сумісності, - підказки стенограми Claude-thinking, обмін токенів часу виконання та отримання - кінцевої точки використання -- `openai`: резервна пряма сумісність для GPT-5.4, нормалізація прямого транспорту - OpenAI, підказки про відсутню автентифікацію з урахуванням Codex, приглушення Spark, синтетичні - рядки каталогу OpenAI/Codex, політика thinking/live-моделей, нормалізація псевдонімів токенів використання (`input` / `output` і сімейства `prompt` / `completion`), спільне - сімейство потоків `openai-responses-defaults` для власних обгорток OpenAI/Codex, - метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень - для `gpt-image-1` та реєстрація вбудованого постачальника генерації відео - для `sora-2` -- `google` і `google-gemini-cli`: резервна пряма сумісність для Gemini 3.1, - власна перевірка replay Gemini, санітизація bootstrap replay, тегований - режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника генерації зображень для моделей Gemini image-preview і вбудована +- `anthropic-vertex`: захист політики replay лише для Claude на трафіку + Anthropic-message +- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника, + очищення thought-signature Gemini на проксійованому трафіку Gemini, ін’єкція proxy + reasoning через сімейство потоків `openrouter-thinking`, пересилання метаданих + маршрутизації та політика cache-TTL +- `github-copilot`: початкове налаштування/вхід через пристрій, резервна сумісність моделей уперед, + підказки транскрипту Claude-thinking, обмін runtime-токенів і отримання endpoint + використання +- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI, + підказки відсутньої автентифікації з урахуванням Codex, приглушення Spark, синтетичні + рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів токенів використання + (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків + `openai-responses-defaults` для нативних обгорток OpenAI/Codex, + метадані сімейства постачальника, вбудована реєстрація постачальника + генерації зображень для `gpt-image-1` і вбудована реєстрація постачальника + генерації відео для `sora-2` +- `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1, + нативна перевірка replay Gemini, очищення bootstrap replay, тегований + режим виводу reasoning, зіставлення сучасних моделей, вбудована реєстрація постачальника генерації зображень + для preview-моделей Gemini image і вбудована реєстрація постачальника генерації відео для моделей Veo; OAuth Gemini CLI також володіє форматуванням токенів профілю автентифікації, розбором токенів використання та отриманням - кінцевої точки квот для поверхонь використання -- `moonshot`: спільний транспорт, нормалізація корисного навантаження thinking, що належить плагіну -- `kilocode`: спільний транспорт, заголовки запиту, що належать плагіну, нормалізація - корисного навантаження reasoning, санітизація thought-signature проксійованого Gemini та політика TTL кешу -- `zai`: резервна пряма сумісність для GLM-5, типові значення `tool_stream`, TTL кешу, - політика binary-thinking/live-моделей, а також автентифікація використання + отримання квот; + endpoint квот для поверхонь використання +- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну +- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, нормалізація payload reasoning, + очищення thought-signature proxy-Gemini і політика cache-TTL +- `zai`: резервна сумісність уперед для GLM-5, значення за замовчуванням `tool_stream`, політика cache-TTL, + політика binary-thinking/live-model і автентифікація використання + отримання квот; невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` -- `xai`: нормалізація власного транспорту Responses, переписування псевдонімів `/fast` для - швидких варіантів Grok, типовий `tool_stream`, очищення схем інструментів / - корисного навантаження reasoning, специфічне для xAI, та вбудована реєстрація постачальника генерації відео +- `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для + швидких варіантів Grok, значення за замовчуванням `tool_stream`, очищення схем інструментів / + payload reasoning для xAI і вбудована реєстрація постачальника генерації відео для `grok-imagine-video` - `mistral`: метадані можливостей, що належать плагіну - `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс - санітизація thought-signature проксійованого Gemini + очищення thought-signature proxy-Gemini - `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan, - таких як `alibaba/wan2.6-t2v` + як-от `alibaba/wan2.6-t2v` - `byteplus`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео для моделей Seedance text-to-video/image-to-video -- `fal`: вбудована реєстрація постачальника генерації відео для розміщеної сторонньої - реєстрації постачальника генерації зображень для моделей зображень FLUX, а також вбудована - реєстрація постачальника генерації відео для розміщених сторонніх відеомоделей +- `fal`: вбудована реєстрація постачальника генерації відео для hosted third-party + реєстрація постачальника генерації зображень для моделей FLUX image плюс вбудована + реєстрація постачальника генерації відео для hosted third-party video models - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`: лише каталоги, що належать плагіну - `qwen`: каталоги, що належать плагіну, для текстових моделей плюс спільні - реєстрації постачальників media-understanding і генерації відео для його - мультимодальних поверхонь; генерація відео Qwen використовує стандартні кінцеві точки DashScope video з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` -- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для власних - моделей на основі задач Runway, таких як `gen4.5` + реєстрації постачальників media-understanding і video-generation для його + мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint DashScope + з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` +- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних + моделей Runway на основі задач, таких як `gen4.5` - `minimax`: каталоги, що належать плагіну, вбудована реєстрація постачальника генерації відео - для моделей відео Hailuo, вбудована реєстрація постачальника генерації зображень - для `image-01`, гібридний вибір політики replay Anthropic/OpenAI - та логіка автентифікації/знімка використання + для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень + для `image-01`, гібридний вибір політики replay Anthropic/OpenAI і логіка + автентифікації/знімків використання - `together`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео для відеомоделей Wan -- `xiaomi`: каталоги, що належать плагіну, плюс логіка автентифікації/знімка використання +- `xiaomi`: каталоги, що належать плагіну, плюс логіка автентифікації/знімків використання -Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальників: `openai` і +Тепер вбудований плагін `openai` володіє обома ідентифікаторами постачальника: `openai` і `openai-codex`. -Це охоплює постачальників, які все ще вписуються у звичайні транспорти OpenClaw. Постачальник, +Це охоплює постачальників, які все ще вписуються в нормальні транспорти OpenClaw. Постачальник, якому потрібен повністю власний виконавець запитів, — це окрема, глибша поверхня розширення. ## Ротація API-ключів - Підтримує загальну ротацію постачальників для вибраних постачальників. - Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (єдиний live-override, найвищий пріоритет) + - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для постачальників Google як резерв також додається `GOOGLE_API_KEY`. -- Порядок вибору ключів зберігає пріоритет і видаляє дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на rate-limit (наприклад, +- Для постачальників Google `GOOGLE_API_KEY` також включено як резервний варіант. +- Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. +- Запити повторюються з наступним ключем лише у відповідях із rate limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Помилки, не пов’язані з rate-limit, завершуються негайно; ротація ключів не виконується. -- Коли всі кандидатні ключі не спрацьовують, повертається фінальна помилка з останньої спроби. +- Збої, не пов’язані з rate limit, завершуються негайно; ротація ключів не виконується. +- Коли всі кандидатні ключі зазнають невдачі, повертається фінальна помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Ці постачальники не потребують -конфігурації `models.providers`; достатньо задати автентифікацію й вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** +конфігурація `models.providers`; достатньо налаштувати автентифікацію та вибрати модель. ### OpenAI - Постачальник: `openai` - Автентифікація: `OPENAI_API_KEY` -- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (єдине перевизначення) +- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) -- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Підігрів WebSocket OpenAI Responses типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) +- Перевизначення для кожної моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Warm-up OpenAI Responses WebSocket за замовчуванням увімкнено через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` маплять прямі запити OpenAI `openai/*` Responses на `service_tier=priority` у `api.openai.com` +- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com` - Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до власного трафіку OpenAI на `api.openai.com`, а не до - загальних OpenAI-сумісних проксі -- Власні маршрути OpenAI також зберігають `store` Responses, підказки кешу промптів і - формування корисного навантаження для сумісності reasoning OpenAI; проксі-маршрути — ні -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки жива API OpenAI його відхиляє; Spark розглядається лише як Codex + `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не + до загальних OpenAI-сумісних проксі +- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і + формування payload сумісності reasoning OpenAI; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається доступним лише для Codex ```json5 { @@ -271,12 +275,12 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Постачальник: `anthropic` - Автентифікація: `ANTHROPIC_API_KEY` -- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (єдине перевизначення) +- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим API-ключем та OAuth, надісланим до `api.anthropic.com`; OpenClaw мапить це на Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Токен налаштування Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим API-ключем і OAuth, надісланим на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Токен налаштування Anthropic усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. ```json5 { @@ -290,16 +294,16 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Автентифікація: OAuth (ChatGPT) - Приклад моделі: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) -- Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також передається у власних запитах Codex Responses (`chatgpt.com/backend-api`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) +- Перевизначення для кожної моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) додаються лише до власного трафіку Codex на + `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі -- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw мапить це на `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` і далі доступний, коли каталог OAuth Codex його показує; залежить від прав доступу -- `openai-codex/gpt-5.4` зберігає власний `contextWindow = 1050000` і типове обмеження часу виконання `contextTokens = 272000`; перевизначте ліміт часу виконання через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OpenAI Codex OAuth офіційно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. +- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від entitlement +- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типові для runtime `contextTokens = 272000`; перевизначте обмеження runtime через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/процесів, таких як OpenClaw. ```json5 { @@ -321,15 +325,15 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста ### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також мапінг кінцевих точок Alibaba DashScope і Coding Plan +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan - [MiniMax](/uk/providers/minimax): доступ MiniMax Coding Plan через OAuth або API-ключ -- [GLM Models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API +- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint ### OpenCode - Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Постачальник часу виконання Zen: `opencode` -- Постачальник часу виконання Go: `opencode-go` +- Постачальник Zen runtime: `opencode` +- Постачальник Go runtime: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -343,30 +347,30 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Постачальник: `google` - Автентифікація: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (єдине перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для передавання власного - дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` + (або застаріле `cached_content`) для пересилання нативного для постачальника + дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` -- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth -- Увага: OAuth Gemini CLI в OpenClaw — неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний OAuth-потік +- Обережно: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. - OAuth Gemini CLI постачається як частина вбудованого плагіна `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - Увімкнення: `openclaw plugins enable google` - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - - Типова модель: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає - токени в профілях автентифікації на хості шлюзу. - - Якщо запити не працюють після входу, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості шлюзу. - - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з + - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` + - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає + токени в профілях автентифікації на хості gateway. + - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. + - JSON-відповіді Gemini CLI аналізуються з `response`; використання резервно береться з `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -376,7 +380,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню + - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню ### Vercel AI Gateway @@ -392,38 +396,37 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; живе - виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити - каталог часу виконання. -- Точна маршрутизація на верхньому рівні за `kilocode/kilo/auto` належить Kilo Gateway, +- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live + виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. +- Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Докладніше про налаштування див. у [/providers/kilocode](/uk/providers/kilocode). +Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). ### Інші вбудовані плагіни постачальників - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Приклад моделі: `openrouter/auto` -- OpenClaw застосовує документовані заголовки атрибуції застосунку OpenRouter лише тоді, коли - запит справді націлений на `openrouter.ai` -- Маркери Anthropic `cache_control`, специфічні для OpenRouter, так само обмежені +- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли + запит справді спрямовано на `openrouter.ai` +- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені перевіреними маршрутами OpenRouter, а не довільними URL проксі -- OpenRouter залишається на проксійному OpenAI-сумісному шляху, тому власне - лише-OpenAI формування запитів (`serviceTier`, `store` Responses, - підказки кешу промптів, payload для сумісності reasoning OpenAI) не передається -- Посилання OpenRouter на базі Gemini зберігають лише санітизацію thought-signature проксійованого Gemini; - власна перевірка replay Gemini та переписування bootstrap залишаються вимкненими +- OpenRouter залишається на проксі-подібному OpenAI-сумісному шляху, тому нативне + формування запитів лише для OpenAI (`serviceTier`, Responses `store`, + підказки prompt-cache, payload сумісності reasoning OpenAI) не пересилається +- Посилання OpenRouter на основі Gemini зберігають лише очищення thought-signature proxy-Gemini; + нативна перевірка replay Gemini і bootstrap-переписування залишаються вимкненими - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Приклад моделі: `kilocode/kilo/auto` -- Посилання Kilo на базі Gemini зберігають той самий шлях санітизації thought-signature - проксійованого Gemini; `kilocode/kilo/auto` та інші підказки, що не підтримують proxy-reasoning, - пропускають упровадження proxy reasoning +- Посилання Kilo на основі Gemini зберігають той самий шлях очищення thought-signature + proxy-Gemini; `kilocode/kilo/auto` та інші підказки про непідтримку proxy-reasoning + пропускають ін’єкцію proxy reasoning - MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth) - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` - Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7` -- Онбординг MiniMax/налаштування API-ключа записує явні визначення моделей M2.7 з - `input: ["text", "image"]`; вбудований каталог постачальника зберігає посилання чату - лише текстовими, доки конфігурація цього постачальника не буде матеріалізована +- Початкове налаштування/API-ключ MiniMax записує явні визначення моделі M2.7 з + `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання + лише текстовими, доки конфігурацію цього постачальника не буде матеріалізовано - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Приклад моделі: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`) @@ -449,11 +452,11 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Приклад моделі: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Власні вбудовані запити xAI використовують шлях xAI Responses + - Нативні вбудовані запити xAI використовують шлях xAI Responses - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast` - - `tool_stream` типово ввімкнено; задайте - `agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб + - `tool_stream` за замовчуванням увімкнений; задайте + `agents.defaults.models["xai/"].params.tool_stream` як `false`, щоб вимкнути його - Mistral: `mistral` (`MISTRAL_API_KEY`) - Приклад моделі: `mistral/mistral-large-latest` @@ -470,14 +473,14 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або OpenAI/Anthropic‑сумісні проксі. -Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог. +Багато з наведених нижче вбудованих плагінів постачальників уже публікують каталог за замовчуванням. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -типовий base URL, заголовки або список моделей. +base URL, заголовки або список моделей за замовчуванням. ### Moonshot AI (Kimi) Moonshot постачається як вбудований плагін постачальника. Використовуйте вбудованого постачальника -типово й додавайте явний запис `models.providers.moonshot` лише тоді, коли +за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити base URL або метадані моделі: - Постачальник: `moonshot` @@ -517,7 +520,7 @@ Moonshot постачається як вбудований плагін пос ### Kimi Coding -Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: +Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI: - Постачальник: `kimi` - Автентифікація: `KIMI_API_KEY` @@ -538,7 +541,7 @@ Kimi Coding використовує Anthropic-сумісну кінцеву т Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Постачальник: `volcengine` (coding: `volcengine-plan`) +- Постачальник: `volcengine` (для coding: `volcengine-plan`) - Автентифікація: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -551,13 +554,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу типово вибирається coding-поверхня, але загальний каталог `volcengine/*` +Початкове налаштування за замовчуванням використовує поверхню coding, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделей під час онбордингу/налаштування вибір автентифікації Volcengine надає перевагу і рядкам +У пікерах моделей під час початкового налаштування/конфігурування вибір автентифікації Volcengine віддає перевагу і рядкам `volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору в межах постачальника. +OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній +пікер у межах постачальника. Доступні моделі: @@ -567,7 +570,7 @@ OpenClaw повертається до нефільтрованого катал - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -Coding-моделі (`volcengine-plan`): +Моделі для coding (`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -575,11 +578,11 @@ Coding-моделі (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (International) +### BytePlus (міжнародний) BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Постачальник: `byteplus` (coding: `byteplus-plan`) +- Постачальник: `byteplus` (для coding: `byteplus-plan`) - Автентифікація: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -592,13 +595,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Під час онбордингу типово вибирається coding-поверхня, але загальний каталог `byteplus/*` +Початкове налаштування за замовчуванням використовує поверхню coding, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделей під час онбордингу/налаштування вибір автентифікації BytePlus надає перевагу і рядкам +У пікерах моделей під час початкового налаштування/конфігурування вибір автентифікації BytePlus віддає перевагу і рядкам `byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору в межах постачальника. +OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній +пікер у межах постачальника. Доступні моделі: @@ -606,7 +609,7 @@ OpenClaw повертається до нефільтрованого катал - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -Coding-моделі (`byteplus-plan`): +Моделі для coding (`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -616,7 +619,7 @@ Coding-моделі (`byteplus-plan`): ### Synthetic -Synthetic надає Anthropic-сумісні моделі за постачальником `synthetic`: +Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: - Постачальник: `synthetic` - Автентифікація: `SYNTHETIC_API_KEY` @@ -644,39 +647,39 @@ Synthetic надає Anthropic-сумісні моделі за постачал ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує власні кінцеві точки: +MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint: -- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` -- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API key (Global): `--auth-choice minimax-global-api` -- MiniMax API key (CN): `--auth-choice minimax-cn-api` +- OAuth MiniMax (Global): `--auth-choice minimax-global-oauth` +- OAuth MiniMax (CN): `--auth-choice minimax-cn-oauth` +- API-ключ MiniMax (Global): `--auth-choice minimax-global-api` +- API-ключ MiniMax (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Докладніше про налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). +Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, -якщо ви явно його не задасте, а `/fast on` переписує +На Anthropic-сумісному streaming-шляху MiniMax OpenClaw вимикає thinking за +замовчуванням, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розподіл можливостей, що належать плагіну: +Поділ можливостей, якими володіє плагін: -- Типові значення тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Значення за замовчуванням для тексту/чату залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це належний плагіну `MiniMax-VL-01` на обох шляхах автентифікації MiniMax +- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax - Вебпошук залишається на ідентифікаторі постачальника `minimax` ### Ollama -Ollama постачається як вбудований плагін постачальника й використовує власне API Ollama: +Ollama постачається як вбудований плагін постачальника і використовує нативний API Ollama: - Постачальник: `ollama` - Автентифікація: не потрібна (локальний сервер) - Приклад моделі: `ollama/llama3.3` -- Встановлення: [https://ollama.com/download](https://ollama.com/download) +- Установлення: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Встановіть Ollama, потім завантажте модель: ollama pull llama3.3 ``` @@ -688,26 +691,26 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте це через -`OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до -`openclaw onboard` і засобу вибору моделей. Докладніше про онбординг, режими cloud/local і користувацьку конфігурацію див. у [/providers/ollama](/uk/providers/ollama). +Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте +його через `OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо в +`openclaw onboard` і пікер моделей. Деталі початкового налаштування, cloud/local режиму та власної конфігурації див. у [/providers/ollama](/uk/providers/ollama). ### vLLM -vLLM постачається як вбудований плагін постачальника для локальних/self-hosted OpenAI-сумісних -серверів: +vLLM постачається як вбудований плагін постачальника для локальних/self-hosted +серверів, сумісних з OpenAI: - Постачальник: `vllm` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типовий base URL: `http://127.0.0.1:8000/v1` +- Base URL за замовчуванням: `http://127.0.0.1:8000/v1` -Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, що повертає `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -717,25 +720,25 @@ export VLLM_API_KEY="vllm-local" } ``` -Докладніше див. у [/providers/vllm](/uk/providers/vllm). +Деталі див. у [/providers/vllm](/uk/providers/vllm). ### SGLang SGLang постачається як вбудований плагін постачальника для швидких self-hosted -OpenAI-сумісних серверів: +серверів, сумісних з OpenAI: - Постачальник: `sglang` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типовий base URL: `http://127.0.0.1:30000/v1` +- Base URL за замовчуванням: `http://127.0.0.1:30000/v1` -Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, що повертає `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -745,11 +748,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Докладніше див. у [/providers/sglang](/uk/providers/sglang). +Деталі див. у [/providers/sglang](/uk/providers/sglang). ### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI‑сумісний): +Приклад (сумісний з OpenAI): ```json5 { @@ -784,20 +787,21 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх не задано, OpenClaw використовує такі типові значення: +- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. + Якщо їх не вказано, OpenClaw використовує такі значення за замовчуванням: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендація: задавайте явні значення, що відповідають лімітам вашого проксі/моделі. -- Для `api: "openai-completions"` на невласних кінцевих точках (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 через непідтримувані ролі `developer`. -- Проксійні OpenAI-сумісні маршрути також пропускають власне лише-OpenAI формування запитів: - без `service_tier`, без `store` Responses, без підказок кешу промптів, без - формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). -- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на невласних кінцевих точках `openai-completions`. +- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 для непідтримуваних ролей `developer`. +- Маршрути проксі-подібного OpenAI-сумісного типу також пропускають нативне формування запитів лише для OpenAI: + без `service_tier`, без Responses `store`, без підказок prompt-cache, без + формування payload сумісності reasoning OpenAI і без прихованих заголовків + атрибуції OpenClaw. +- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). +- З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`. ## Приклади CLI @@ -807,11 +811,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. +Див. також: [/gateway/configuration](/uk/gateway/configuration), де наведено повні приклади конфігурації. ## Пов’язане - [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми - [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб -- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей -- [Providers](/uk/providers) — інструкції з налаштування для кожного постачальника +- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделі +- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index aa64371bf..2ce8117a3 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -3,24 +3,24 @@ read_when: - Створення або налагодження нативних плагінів OpenClaw - Розуміння моделі можливостей плагінів або меж володіння - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація хуків часу виконання провайдера або плагінів каналів + - Реалізація хуків середовища виконання провайдера або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішні механізми плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' -title: Внутрішні механізми плагінів +summary: 'Внутрішня будова плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' +title: Внутрішня будова плагінів x-i18n: - generated_at: "2026-04-07T20:12:37Z" + generated_at: "2026-04-08T18:12:38Z" model: gpt-5.4 provider: openai - source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 + source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішні механізми плагінів +# Внутрішня будова плагінів - Це **детальний довідник з архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача + Це **довідник із глибокої архітектури**. Практичні посібники див. тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей @@ -31,48 +31,48 @@ x-i18n: ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** в 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 реєстрації можливостей — це напрямок, якого слід дотримуватися +- застарілі хуки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час переходу +- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому задокументованому + контракту, а не випадковим експортуванням допоміжних засобів ### Форми плагінів @@ -82,42 +82,43 @@ OpenClaw класифікує кожен завантажений плагін - **plain-capability** -- реєструє рівно один тип можливості (наприклад, плагін лише провайдера, як-от `mistral`) - **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовим виведенням, мовленням, розумінням медіа та генерацією + `openai` володіє текстовим інференсом, мовленням, розумінням медіа та генерацією зображень) - **hook-only** -- реєструє лише хуки (типізовані або користувацькі), без можливостей, - інструментів, команд або сервісів -- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості + інструментів, команд чи сервісів +- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але без + можливостей -Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та розподіл -можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). +Використайте `openclaw plugins inspect `, щоб побачити форму плагіна та розподіл +можливостей. Подробиці див. у [довідці CLI](/cli/plugins#inspect). ### Застарілі хуки Хук `before_agent_start` залишається підтримуваним як шлях сумісності для -плагінів лише з хуками. Застарілі реальні плагіни все ще залежать від нього. +плагінів лише з хуками. Від нього все ще залежать реальні застарілі плагіни. Напрямок: - зберігати його працездатність - документувати його як застарілий -- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve` -- для мутації промпта надавати перевагу `before_prompt_build` -- видаляти лише після того, як реальне використання зменшиться, а покриття фікстурами доведе безпечність міграції +- надавати перевагу `before_model_resolve` для роботи з перевизначенням моделі/провайдера +- надавати перевагу `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` лише викликає попередження. Ці +Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш плагін -- +`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури @@ -125,59 +126,59 @@ OpenClaw класифікує кожен завантажений плагін Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить потенційні плагіни з налаштованих шляхів, коренів workspace, - глобальних коренів розширень і комплектних розширень. Виявлення спочатку читає нативні - маніфести `openclaw.plugin.json` та підтримувані маніфести пакетів. + OpenClaw знаходить потенційні плагіни з налаштованих шляхів, коренів робочих областей, + глобальних коренів розширень і вбудованих розширень. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json` разом із підтримуваними маніфестами пакунків. 2. **Увімкнення + валідація** - Ядро вирішує, чи виявлений плагін увімкнено, вимкнено, заблоковано або - вибрано для ексклюзивного слота, такого як пам’ять. -3. **Завантаження часу виконання** - Нативні плагіни OpenClaw завантажуються в тому самому процесі через jiti та реєструють - можливості в центральному реєстрі. Сумісні пакети нормалізуються в - записи реєстру без імпорту коду часу виконання. -4. **Споживання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування - провайдерів, хуки, HTTP-маршрути, команди CLI та сервіси. + Ядро визначає, чи знайдений плагін увімкнений, вимкнений, заблокований, або + вибраний для ексклюзивного слоту, такого як пам’ять. +3. **Завантаження середовища виконання** + Нативні плагіни OpenClaw завантажуються в межах процесу через jiti і реєструють + можливості в центральному реєстрі. Сумісні пакунки нормалізуються в записи + реєстру без імпорту коду середовища виконання. +4. **Використання поверхонь** + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування провайдерів, + хуки, HTTP-маршрути, CLI-команди та сервіси. -Спеціально для CLI плагінів виявлення кореневих команд поділено на дві фази: +Зокрема для CLI плагінів, виявлення кореневих команд поділено на дві фази: -- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })` -- справжній модуль CLI плагіна може залишатися лінивим і реєструватися при першому виклику +- метадані на етапі парсингу надходять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику -Це дозволяє тримати CLI-код, що належить плагіну, всередині плагіна, і при цьому дає OpenClaw -можливість резервувати імена кореневих команд до розбору. +Це дозволяє тримати код CLI, що належить плагіну, всередині плагіна, водночас даючи OpenClaw +можливість резервувати імена кореневих команд до парсингу. Важлива межа дизайну: - виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** без виконання коду плагіна -- нативна поведінка часу виконання надходить із шляху `register(api)` модуля плагіна +- нативна поведінка середовища виконання походить зі шляху `register(api)` модуля плагіна -Цей поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки UI/схеми до того, як повне середовище часу виконання стане активним. +Це розділення дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки для UI/схем ще до повної активації середовища виконання. -### Плагіни каналів і спільний інструмент message +### Плагіни каналів і спільний інструмент повідомлень -Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для -звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у ядрі, а -плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. +Плагінам каналів не потрібно реєструвати окремий інструмент для надсилання/редагування/реакції для +звичайних дій чату. OpenClaw зберігає один спільний інструмент `message` у ядрі, а +плагіни каналів володіють канал-специфічним виявленням і виконанням за ним. Поточна межа така: -- ядро володіє спільним хостом інструмента `message`, прив’язкою промптів, обліком - сесій/гілок і диспетчеризацією виконання -- плагіни каналів володіють виявленням дій у межах області, виявленням можливостей - і будь-якими фрагментами схеми, специфічними для каналу -- плагіни каналів володіють граматикою розмови сесії, специфічною для провайдера, наприклад +- ядро володіє спільним хостом інструмента `message`, прив’язкою до промптів, обліком сесій/гілок + і диспетчеризацією виконання +- плагіни каналів володіють виявленням scoped actions, виявленням можливостей і будь-якими + фрагментами схем, специфічними для каналу +- плагіни каналів володіють граматикою розмов у сесіях, специфічною для провайдера, зокрема тим, як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов - плагіни каналів виконують фінальну дію через свій адаптер дій -Для плагінів каналів поверхнею SDK є -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну разом повертати свої видимі дії, можливості та -внески до схеми, щоб ці частини не розходилися. +Для плагінів каналів поверхня SDK — +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик +виявлення дозволяє плагіну повертати видимі дії, можливості та внески в схему +разом, щоб ці частини не розходилися. -Ядро передає область часу виконання в цей крок виявлення. Важливі поля включають: +Ядро передає область виконання в цей крок виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -188,122 +189,122 @@ OpenClaw класифікує кожен завантажений плагін - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для контекстно-залежних плагінів. Канал може приховувати або показувати -дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або -довіреної особи відправника-запитувача без жорстко закодованих гілок у -інструменті ядра `message`. +Це важливо для контекстно-чутливих плагінів. Канал може приховувати або показувати +дії з повідомленнями залежно від активного облікового запису, поточної кімнати/гілки/повідомлення чи +довіреної ідентичності відправника, без жорсткого кодування гілок, специфічних для каналу, +в інструменті ядра `message`. -Ось чому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner -відповідає за пересилання поточної ідентичності чату/сесії в межу виявлення плагіна, -щоб спільний інструмент `message` показував правильну поверхню каналу, що належить -поточному ходу. +Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner +відповідає за передачу поточної ідентичності чату/сесії в межу виявлення плагіна, щоб +спільний інструмент `message` показував правильну поверхню, що належить каналу, для поточного ходу. -Для допоміжних засобів виконання, що належать каналу, комплектні плагіни повинні тримати -середовище виконання всередині власних модулів розширення. Ядро більше не володіє -середовищами виконання дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і комплектні -плагіни повинні імпортувати свій локальний код часу виконання безпосередньо зі своїх +Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають тримати логіку виконання +усередині власних модулів розширення. Ядро більше не володіє середовищами виконання message-action +для Discord, Slack, Telegram чи WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані +плагіни мають імпортувати власний локальний код середовища виконання безпосередньо зі своїх модулів розширення. -Та сама межа застосовується до загалом вендор-іменованих швів SDK: ядро не повинно -імпортувати зручні барабани, специфічні для каналів Slack, Discord, Signal, -WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, воно має або -використовувати власний барабан `api.ts` / `runtime-api.ts` комплектного плагіна, або підняти цю потребу -до вузької загальної можливості в спільному SDK. +Та сама межа застосовується і до SDK-швів, названих на честь провайдерів, загалом: ядро не повинно +імпортувати канал-специфічні convenience barrels для Slack, Discord, Signal, +WhatsApp чи подібних розширень. Якщо ядру потрібна певна поведінка, воно має або +використовувати власний barrel `api.ts` / `runtime-api.ts` вбудованого плагіна, або підняти +цю потребу до вузької загальної можливості в спільному SDK. -Для опитувань зокрема є два шляхи виконання: +Зокрема для опитувань, існують два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну - модель опитувань -- `actions.handleAction("poll")` — бажаний шлях для семантики опитувань, специфічної для каналу, або додаткових параметрів опитування +- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній + моделі опитувань +- `actions.handleAction("poll")` — це бажаний шлях для специфічної для каналу + семантики опитувань або додаткових параметрів опитувань Тепер ядро відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна -відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати поля опитування, -специфічні для каналу, не блокуючись спочатку загальним парсером опитувань. +відхиляє дію, тож обробники опитувань, що належать плагіну, можуть приймати специфічні для каналу поля +опитування, не блокуючись спочатку загальним парсером опитувань. Повну послідовність запуску див. у [Конвеєр завантаження](#load-pipeline). ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір не пов’язаних інтеграцій. +**функції**, а не як мішок не пов’язаних між собою інтеграцій. Це означає: -- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії -- плагін функції зазвичай має володіти повною поверхнею функції, яку він вводить -- канали мають споживати спільні можливості ядра замість того, щоб повторно реалізовувати - поведінку провайдера ad hoc +- плагін компанії зазвичай має володіти всіма поверхнями цієї компанії в OpenClaw +- плагін функції зазвичай має володіти повною поверхнею функції, яку він додає +- канали мають споживати спільні можливості ядра замість випадкового повторного впровадження + поведінки провайдерів Приклади: -- комплектний плагін `openai` володіє поведінкою провайдера моделей OpenAI і поведінкою OpenAI для - мовлення + голосу в реальному часі + розуміння медіа + генерації зображень -- комплектний плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs -- комплектний плагін `microsoft` володіє поведінкою мовлення Microsoft -- комплектний плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google для - розуміння медіа + генерації зображень + веб-пошуку -- комплектний плагін `firecrawl` володіє поведінкою веб-отримання Firecrawl -- комплектні плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми +- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та поведінкою OpenAI + для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs +- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft +- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google + для розуміння медіа + генерації зображень + вебпошуку +- вбудований плагін `firecrawl` володіє поведінкою отримання з вебу Firecrawl +- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми бекендами розуміння медіа -- комплектний плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також - поведінкою розуміння медіа та генерації відео -- плагін `voice-call` — це плагін функції: він володіє транспортом дзвінків, інструментами, - CLI, маршрутами та мостом медіапотоків Twilio, але споживає спільні можливості мовлення, - а також транскрипції та голосу в реальному часі замість прямого імпорту вендорних плагінів +- вбудований плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також + розумінням медіа і генерацією відео +- плагін `voice-call` — це плагін функції: він володіє транспортом викликів, інструментами, + CLI, маршрутами та мостом Twilio media-stream, але споживає спільні можливості мовлення + плюс транскрипцію та голос у реальному часі замість прямого імпорту vendor-плагінів -Бажаний кінцевий стан: +Очікуваний кінцевий стан: -- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та +- OpenAI живе в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший вендор може робити так само для власної поверхні -- каналам не важливо, який плагін вендора володіє провайдером; вони споживають +- інший вендор може робити те саме для власної поверхні +- каналам байдуже, який vendor-плагін володіє провайдером; вони споживають спільний контракт можливості, який надає ядро -Ось ключова відмінність: +Це ключова відмінність: - **plugin** = межа володіння -- **capability** = контракт ядра, який кілька плагінів можуть реалізовувати або споживати +- **capability** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів -Тож якщо OpenClaw додає нову доменну область, таку як відео, перше запитання не -«який провайдер має жорстко закодувати обробку відео?» Перше запитання — -«який контракт можливості відео в ядрі?» Щойно цей контракт з’явиться, вендорні плагіни +Отже, якщо OpenClaw додає новий домен, наприклад відео, перше запитання не таке: +«який провайдер має жорстко кодувати обробку відео?» Перше запитання таке: «який +контракт можливості відео в ядрі?» Щойно цей контракт з’явиться, vendor-плагіни зможуть реєструватися для нього, а плагіни каналів/функцій — споживати його. -Якщо можливості ще не існує, зазвичай правильний крок такий: +Якщо можливості ще не існує, правильним кроком зазвичай є: 1. визначити відсутню можливість у ядрі -2. відкрити її через API/середовище часу виконання плагіна у типізований спосіб +2. відкрити її через API/середовище виконання плагіна в типізований спосіб 3. підключити канали/функції до цієї можливості -4. дозволити вендорним плагінам реєструвати реалізації +4. дозволити vendor-плагінам реєструвати реалізації -Це зберігає явне володіння, водночас уникаючи поведінки ядра, яка залежить від -одного вендора або одноразового коду шляху, специфічного для плагіна. +Це зберігає явне володіння, водночас уникаючи поведінки ядра, що залежить від +одного вендора або одноразового шляху коду, специфічного для плагіна. -### Шарування можливостей +### Нашарування можливостей -Використовуйте цю ментальну модель, коли вирішуєте, де має належати код: +Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: -- **шар можливостей ядра**: спільна оркестрація, політика, резервний шлях, правила - злиття конфігурації, семантика доставки та типізовані контракти -- **шар вендорного плагіна**: вендор-специфічні API, автентифікація, каталоги моделей, синтез - мовлення, генерація зображень, майбутні бекенди відео, кінцеві точки використання +- **шар можливостей ядра**: спільна оркестрація, політики, резервні варіанти, правила + об’єднання конфігурації, семантика доставки та типізовані контракти +- **шар vendor-плагіна**: vendor-специфічні API, автентифікація, каталоги моделей, синтез мовлення, + генерація зображень, майбутні бекенди відео, endpoint-и використання - **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості ядра та представляє їх на поверхні + яка споживає можливості ядра і представляє їх на поверхні Наприклад, TTS має таку форму: -- ядро володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями та доставкою в канал +- ядро володіє політикою TTS під час відповіді, порядком резервування, уподобаннями та доставкою в канал - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний засіб часу виконання TTS для телефонії +- `voice-call` споживає допоміжний засіб середовища виконання телекомунікаційного TTS -Той самий шаблон слід віддавати перевагу для майбутніх можливостей. +Цей самий шаблон слід віддавати перевагу для майбутніх можливостей. ### Приклад плагіна компанії з кількома можливостями -Плагін компанії має виглядати цілісно ззовні. Якщо в OpenClaw є спільні +Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веб-отримання та веб-пошуку, +генерації зображень, генерації відео, отримання з вебу та вебпошуку, вендор може володіти всіма своїми поверхнями в одному місці: ```ts @@ -363,218 +364,215 @@ export default plugin; - один плагін володіє поверхнею вендора - ядро все одно володіє контрактами можливостей - канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора -- тести контрактів можуть перевіряти, що плагін зареєстрував можливості, якими - він заявляє, що володіє +- контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими він + заявляє, що володіє ### Приклад можливості: розуміння відео OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. До неї застосовується та сама модель володіння: +можливість. Тут застосовується та сама модель володіння: 1. ядро визначає контракт розуміння медіа -2. вендорні плагіни реєструють `describeImage`, `transcribeAudio` і +2. vendor-плагіни реєструють `describeImage`, `transcribeAudio` і `describeVideo` за потреби -3. канали та плагіни функцій споживають спільну поведінку ядра, а не - підключаються безпосередньо до коду вендора +3. канали та плагіни функцій споживають спільну поведінку ядра замість + прямої прив’язки до коду вендора -Це дозволяє не вбудовувати припущення одного провайдера щодо відео в ядро. Плагін володіє +Це дозволяє не закладати припущення одного провайдера щодо відео в ядро. Плагін володіє поверхнею вендора; ядро володіє контрактом можливості та резервною поведінкою. Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим -контрактом можливості та допоміжним засобом часу виконання, а вендорні плагіни реєструють -реалізації `api.registerVideoGenerationProvider(...)` для нього. +контрактом можливості та допоміжним засобом середовища виконання, а vendor-плагіни реєструють +реалізації `api.registerVideoGenerationProvider(...)` для неї. -Потрібен конкретний контрольний список розгортання? Див. -[Cookbook можливостей](/uk/plugins/architecture). +Потрібен конкретний контрольний список для впровадження? Див. +[Практичний посібник з можливостей](/uk/plugins/architecture). ## Контракти та примусове забезпечення -Поверхня API плагінів навмисно типізована та централізована в +Поверхня API плагіна навмисно типізована і централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -допоміжні засоби часу виконання, на які може покладатися плагін. +допоміжні засоби середовища виконання, на які може спиратися плагін. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт -- ядро може відхиляти дубльоване володіння, наприклад, коли два плагіни реєструють той самий - id провайдера -- під час запуску можна показувати зрозумілу діагностику для некоректної реєстрації -- тести контрактів можуть забезпечувати володіння комплектних плагінів і запобігати тихому дрейфу +- ядро може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють один і той самий + ідентифікатор провайдера +- під час запуску можна показувати придатні до дії діагностичні повідомлення для некоректних реєстрацій +- контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати тихому дрейфу Є два шари забезпечення: -1. **забезпечення реєстрації часу виконання** +1. **забезпечення реєстрації під час виконання** Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: - дубльовані id провайдерів, дубльовані id провайдерів мовлення та некоректні - реєстрації призводять до діагностики плагіна, а не до невизначеної поведінки. -2. **тести контрактів** - Комплектні плагіни фіксуються в реєстрах контрактів під час запуску тестів, щоб + дубльовані ідентифікатори провайдерів, дубльовані ідентифікатори провайдерів мовлення та некоректні + реєстрації породжують діагностику плагінів замість невизначеної поведінки. +2. **контрактні тести** + Вбудовані плагіни під час тестів захоплюються в контрактні реєстри, щоб OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для моделей - провайдерів, провайдерів мовлення, провайдерів веб-пошуку та володіння комплектною реєстрацією. + провайдерів, провайдерів мовлення, провайдерів вебпошуку та володіння реєстрацією вбудованих плагінів. -Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою -поверхнею володіє. Це дозволяє ядру та каналам безшовно поєднуватися, оскільки володіння -оголошене, типізоване та перевірюване, а не неявне. +Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою +поверхнею володіє. Це дозволяє ядру та каналам безшовно компонуватися, оскільки +володіння оголошене, типізоване та придатне до тестування, а не неявне. -### Що має належати контракту +### Що належить до контракту Хороші контракти плагінів: - типізовані -- невеликі -- специфічні для можливості +- малі +- специфічні до можливості - належать ядру -- придатні до повторного використання кількома плагінами -- споживані каналами/функціями без знання про вендора +- повторно використовуються кількома плагінами +- можуть споживатися каналами/функціями без знань про вендора Погані контракти плагінів: -- вендор-специфічна політика, прихована в ядрі -- одноразові обхідні шляхи для плагіна, які оминають реєстр -- код каналу, що звертається прямо до реалізації вендора -- ad hoc об’єкти часу виконання, які не є частиною `OpenClawPluginApi` або +- специфічна для вендора політика, прихована в ядрі +- одноразові аварійні виходи плагінів, які обходять реєстр +- код каналу, що напряму заходить у реалізацію вендора +- ad hoc об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім +Якщо сумніваєтесь, підніміть рівень абстракції: спочатку визначте можливість, а потім дозвольте плагінам підключатися до неї. ## Модель виконання -Нативні плагіни OpenClaw працюють **в тому самому процесі**, що й Gateway. Вони не -ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й -код ядра. +Нативні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не +ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що +й код ядра. Наслідки: - нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси -- помилка нативного плагіна може призвести до аварійного завершення або дестабілізації gateway -- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині - процесу OpenClaw +- помилка нативного плагіна може призвести до збою або дестабілізації gateway +- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні пакети безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх -як пакети метаданих/вмісту. У поточних випусках це переважно означає комплектні +Сумісні пакунки безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх +як пакети метаданих/вмісту. У поточних релізах це переважно означає вбудовані Skills. -Використовуйте allowlist і явні шляхи встановлення/завантаження для некомплектних плагінів. Розглядайте -workspace-плагіни як код для етапу розробки, а не як типові значення для production. +Для невбудованих плагінів використовуйте allowlist-и та явні шляхи встановлення/завантаження. Розглядайте +плагіни робочої області як код для розробки, а не стандарт для продакшну. -Для назв пакетів комплектних workspace тримайте id плагіна прив’язаним до npm-імені: -`@openclaw/` за замовчуванням або зі схваленим типізованим суфіксом, таким як -`-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли +Для назв пакетів у вбудованій робочій області зберігайте прив’язку ідентифікатора плагіна в npm-імені: +`@openclaw/` за замовчуванням або затверджений типізований суфікс, наприклад +`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли пакет навмисно надає вужчу роль плагіна. Важлива примітка щодо довіри: -- `plugins.allow` довіряє **id плагінів**, а не походженню джерела. -- Workspace-плагін з тим самим id, що й комплектний плагін, навмисно затіняє - комплектну копію, коли цей workspace-плагін увімкнено/внесено до allowlist. -- Це нормально й корисно для локальної розробки, тестування патчів і hotfix. +- `plugins.allow` довіряє **ідентифікаторам плагінів**, а не походженню джерела. +- Плагін робочої області з тим самим ідентифікатором, що й вбудований плагін, навмисно затіняє + вбудовану копію, коли цей плагін робочої області увімкнено/додано до allowlist. +- Це нормально і корисно для локальної розробки, тестування патчів і hotfix-ів. ## Межа експорту -OpenClaw експортує можливості, а не зручні допоміжні реалізації. +OpenClaw експортує можливості, а не реалізаційні зручності. -Зберігайте публічність реєстрації можливостей. Прибирайте непублічні допоміжні експорти: +Зберігайте публічною реєстрацію можливостей. Скорочуйте експорти допоміжних засобів, що не є контрактними: -- підшляхи допоміжних засобів, специфічні для комплектного плагіна -- підшляхи інфраструктури часу виконання, які не призначені як публічний API -- вендор-специфічні зручні допоміжні засоби +- підшляхи допоміжних засобів, специфічних для вбудованих плагінів +- підшляхи інфраструктури середовища виконання, не призначені як публічний API +- convenience helpers, специфічні для вендора - допоміжні засоби налаштування/онбордингу, які є деталями реалізації -Деякі підшляхи допоміжних засобів комплектних плагінів усе ще залишаються в згенерованій карті експорту SDK -заради сумісності та підтримки комплектних плагінів. Поточні приклади включають +Деякі підшляхи допоміжних засобів вбудованих плагінів досі залишаються в згенерованій карті експорту SDK +заради сумісності та підтримки вбудованих плагінів. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для +`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх +як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх плагінів. ## Конвеєр завантаження Під час запуску OpenClaw приблизно робить таке: -1. виявляє корені потенційних плагінів -2. читає нативні або сумісні маніфести пакетів і метадані пакетів +1. виявляє потенційні корені плагінів +2. читає нативні або сумісні маніфести пакунків і метадані package 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. вирішує, чи вмикати кожного кандидата +5. вирішує увімкнення для кожного кандидата 6. завантажує увімкнені нативні модулі через jiti -7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів -8. відкриває реєстр для команд/поверхонь часу виконання +7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий синонім) і збирає реєстрації в реєстр плагінів +8. надає реєстр командам/поверхням середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі комплектні плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. +`activate` — це застарілий синонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання під час часу виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня плагіна, шлях доступний для запису всім, або -власність шляху виглядає підозріло для некомплектних плагінів. +Перевірки безпеки відбуваються **до** виконання коду середовища виконання. Кандидати блокуються, +коли entry виходить за межі кореня плагіна, шлях є глобально записуваним або +володіння шляхом виглядає підозріло для невбудованих плагінів. -### Поведінка manifest-first +### Поведінка з пріоритетом маніфесту -Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: +Маніфест — це джерело істини для керуючої площини. OpenClaw використовує його, щоб: - ідентифікувати плагін -- виявити оголошені канали/Skills/схему конфігурації або можливості пакета -- перевірити `plugins.entries..config` -- доповнити мітки/плейсхолдери Control UI +- виявляти оголошені канали/Skills/схеми конфігурації або можливості пакунка +- перевіряти `plugins.entries..config` +- доповнювати мітки/placeholder-и в Control UI - показувати метадані встановлення/каталогу -Для нативних плагінів модуль часу виконання є частиною data plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. +Для нативних плагінів модуль середовища виконання — це частина площини даних. Він реєструє +фактичну поведінку, наприклад хуки, інструменти, команди або потоки провайдерів. ### Що кешує завантажувач -OpenClaw тримає короткі внутрішньопроцесні кеші для: +OpenClaw підтримує короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- реєстрів завантажених плагінів +- завантажених реєстрів плагінів -Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно +Ці кеші зменшують ривкове навантаження під час запуску та повторні витрати команд. Їх безпечно сприймати як короткоживучі кеші продуктивності, а не як постійне зберігання. Примітка щодо продуктивності: - Встановіть `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 +- CLI-реєстратори - фонові сервіси - команди, що належать плагіну -Потім функції ядра читають із цього реєстру замість прямої взаємодії з модулями плагінів. -Це зберігає односторонність завантаження: +Потім можливості ядра читають із цього реєстру замість прямої взаємодії з модулями плагінів. +Це зберігає односпрямованість завантаження: - модуль плагіна -> реєстрація в реєстрі -- середовище часу виконання ядра -> споживання реєстру +- середовище виконання ядра -> споживання реєстру Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «читати реєстр», а не «обробляти особливі випадки кожного -модуля плагіна». +лише одна точка інтеграції: «прочитати реєстр», а не «створювати special-case для кожного модуля плагіна». ## Колбеки прив’язки розмов -Плагіни, які прив’язують розмову, можуть реагувати, коли погодження вирішено. +Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як -запит на прив’язку буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку буде схвалено або відхилено: ```ts export default { @@ -594,27 +592,28 @@ export default { }; ``` -Поля корисного навантаження колбека: +Поля payload колбека: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: визначена прив’язка для схвалених запитів -- `request`: початкове зведення запиту, підказка від’єднання, id відправника та +- `binding`: вирішена прив’язка для схвалених запитів +- `request`: зведення початкового запиту, підказка від’єднання, ідентифікатор відправника та метадані розмови -Цей колбек призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати -розмову, і запускається після завершення обробки погодження ядром. +Цей колбек призначений лише для сповіщення. Він не змінює того, хто має право прив’язувати +розмову, і виконується після завершення обробки схвалення в ядрі. -## Хуки часу виконання провайдера +## Хуки середовища виконання провайдера -Тепер плагіни провайдерів мають два шари: +Плагіни провайдерів тепер мають два шари: - метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера - до завантаження часу виконання, `channelEnvVars` для дешевого пошуку env/setup каналу - до завантаження часу виконання, а також `providerAuthChoices` для дешевого онбордингу/вибору автентифікації, - міток і метаданих прапорців CLI до завантаження часу виконання + до завантаження середовища виконання, `providerAuthAliases` для варіантів провайдера, що + мають спільну автентифікацію, `channelEnvVars` для дешевого пошуку env/setup каналу до + завантаження середовища виконання, а також `providerAuthChoices` для дешевих міток onboarding/auth-choice і + метаданих прапорців CLI до завантаження середовища виконання - хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- хуки часу виконання: `normalizeModelId`, `normalizeTransport`, +- хуки середовища виконання: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -634,86 +633,88 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскриптів і -політикою інструментів. Ці хуки — поверхня розширення для специфічної поведінки провайдера без -потреби в повністю кастомному транспорті виведення. +OpenClaw і далі володіє загальним агентним циклом, failover, обробкою стенограм і +політикою інструментів. Ці хуки — це поверхня розширення для поведінки, специфічної для провайдера, без +потреби в цілком власному транспорті інференсу. Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker повинні бачити без завантаження середовища -часу виконання плагіна. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI онбордингу/вибору auth -мають знати про id вибору провайдера, мітки груп і просте -підключення auth одним прапорцем без завантаження середовища часу виконання провайдера. Зберігайте `envVars` у середовищі -часу виконання провайдера для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування -OAuth client-id/client-secret. +які загальні шляхи auth/status/model-picker мають бачити без завантаження середовища виконання плагіна. +Використовуйте `providerAuthAliases` у маніфесті, коли один ідентифікатор провайдера має повторно +використовувати env vars, auth profiles, auth на основі конфігурації та варіант onboarding choice API-key іншого ідентифікатора провайдера. +Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI для onboarding/auth-choice +мають знати ідентифікатор choice провайдера, мітки груп та просте підключення автентифікації одним прапорцем +без завантаження середовища виконання провайдера. Зберігайте `envVars` середовища виконання провайдера для +операторських підказок, таких як мітки onboarding або змінні налаштування OAuth +client-id/client-secret. -Використовуйте `channelEnvVars` у маніфесті, коли канал має auth або setup, що керуються env, -які загальний shell-env fallback, перевірки config/status або підказки setup -повинні бачити без завантаження середовища часу виконання каналу. +Використовуйте `channelEnvVars` у маніфесті, коли канал має автентифікацію або налаштування на основі env, +які generic shell-env fallback, перевірки config/status або запити налаштування мають бачити +без завантаження середовища виконання каналу. -### Порядок і використання хуків +### Порядок хуків і використання -Для плагінів моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для вибору рішення. +Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це швидкий посібник для ухвалення рішення. -| # | Хук | Що він робить | Коли використовувати | -| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | -| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не є хуком плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id до пошуку | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тому самому сімействі транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення середовища часу виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; комплектні допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігураційних провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевими точками | -| 7 | `resolveConfigApiKey` | Визначає env-marker auth для конфігураційних провайдерів до завантаження auth часу виконання | Провайдер має власне визначення API-key через env-marker; `amazon-bedrock` також має вбудований AWS env-marker resolver тут | -| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або заснований на config auth без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове `persistence` — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних placeholder-профілів порівняно з auth на основі env/config | Провайдер зберігає синтетичні placeholder-профілі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний fallback для model id, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний warm-up, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для вендорних моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспорті, не перебираючи на себе провайдера | -| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості сімейства транскриптів/провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт виходу reasoning | Провайдеру потрібен tagged reasoning/final output замість native полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | -| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані для окремого ходу транспорту | Провайдер хоче, щоб загальні транспорти надсилали власну для провайдера ідентичність ходу | -| 23 | `resolveWebSocketSessionPolicy` | Додає native WebSocket-заголовки або політику cool-down сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику fallback | -| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` під час виконання | Провайдер зберігає додаткові auth-метадані та потребує користувацької форми токена часу виконання | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилок оновлення | Провайдер не підходить під спільні оновлювачі `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка відновлення, що додається, коли оновлення OAuth не вдається | Провайдеру потрібні власні поради щодо відновлення auth після помилки оновлення | -| 27 | `matchesContextOverflowError` | Матчер переповнення context window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі API/транспортні помилки з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутності auth | Провайдеру потрібна власна підказка відновлення при відсутності auth | -| 31 | `suppressBuiltInModel` | Приглушення застарілої upstream-моделі плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і селекторах | -| 33 | `isBinaryThinking` | Перемикач on/off reasoning для провайдерів із binary thinking | Провайдер надає лише двійкове thinking on/off | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 36 | `isModernModelRef` | Матчер modern-model для live-фільтрів профілів і вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ часу виконання безпосередньо перед виведенням | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 38 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібний користувацький розбір токена usage/quota або інші облікові дані usage | -| 39 | `fetchUsageSnapshot` | Отримує і нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна власна кінцева точка usage або парсер корисного навантаження | -| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті повинна жити разом із плагіном провайдера | -| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, вилучення thinking-блоків) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні власні переписування replay понад спільні допоміжні засоби компактизації | -| 43 | `validateReplayTurns` | Фінальна валідація або переформування ходів replay перед embedded runner | Транспорт провайдера потребує суворішої валідації ходів після загальної санітаризації | -| 44 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| # | Hook | Що робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `baseUrl` | +| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації провайдера під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | +| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не є хуком плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдерів перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в тій самій сім’ї транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби Google-family також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурацій провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від endpoint-а | +| 7 | `resolveConfigApiKey` | Визначає env-marker auth для конфігураційних провайдерів до завантаження auth під час виконання | Провайдер має власне визначення API-key env-marker; `amazon-bedrock` також має вбудований AWS env-marker resolver тут | +| 8 | `resolveSyntheticAuth` | Виносить local/self-hosted або auth на основі конфігурації без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth profiles провайдера; `persistence` за замовчуванням — `runtime-only` для CLI/app-owned creds | Провайдер повторно використовує зовнішні auth credentials без збереження скопійованих refresh tokens | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic profile placeholders відносно auth на основі env/config | Провайдер зберігає synthetic placeholder profiles, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний fallback для model id провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні model id з upstream | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає compat flags для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy transports, не перебираючи на себе провайдера | +| 15 | `capabilities` | Метадані стенограми/інструментів провайдера, що використовуються спільною логікою ядра | Провайдеру потрібні особливості стенограм/сімейства провайдерів | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить embedded runner | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Виводить діагностику схем провайдера після нормалізації | Провайдер хоче мати попередження щодо ключових слів, не навчаючи ядро правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед generic wrappers параметрів потоку | Провайдеру потрібні стандартні параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку на користувацький транспорт | Провайдеру потрібен власний wire protocol, а не просто wrapper | +| 21 | `wrapStreamFn` | Wrapper потоку після застосування generic wrappers | Провайдеру потрібні wrappers заголовків/тіла запиту/сумісності моделей без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані для конкретного ходу транспорту | Провайдер хоче, щоб generic transports надсилали native turn identity провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику cool-down сесії | Провайдер хоче, щоб generic WS transports налаштовували заголовки сесії або fallback policy | +| 24 | `formatApiKey` | Форматтер auth-profile: збережений профіль стає runtime рядком `apiKey` | Провайдер зберігає додаткові auth metadata і потребує користувацької форми runtime token | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких refresh endpoint-ів або політики помилок оновлення | Провайдер не відповідає спільним refreshers `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка щодо виправлення, що додається, коли оновлення OAuth не вдається | Провайдеру потрібна власна підказка з ремонту auth після помилки оновлення | +| 27 | `matchesContextOverflowError` | Власний matcher переповнення вікна контексту провайдера | Провайдер має сирі помилки переповнення, які generic heuristics не виявляють | +| 28 | `classifyFailoverReason` | Власна класифікація причини failover провайдера | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul провайдерів | Провайдеру потрібне керування cache TTL, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна для загального повідомлення про відновлення після відсутності auth | Провайдеру потрібна власна підказка відновлення після відсутності auth | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream моделей плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховувати застарілі upstream rows або заміняти їх підказкою вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки для прямої сумісності в майбутньому в `models list` і picker-ах | +| 33 | `isBinaryThinking` | Перемикач reasoning on/off для провайдерів binary-thinking | Провайдер надає лише binary thinking on/off | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для частини моделей | +| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 36 | `isModernModelRef` | Matcher сучасних моделей для live profile filters і smoke selection | Провайдер володіє зіставленням preferred-model для live/smoke | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 38 | `resolveUsageAuth` | Визначає credentials для usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір usage/quota token або інші credentials usage | +| 39 | `fetchUsageSnapshot` | Отримує і нормалізує usage/quota snapshots провайдера після визначення auth | Провайдеру потрібен власний usage endpoint або parser payload | +| 40 | `createEmbeddingProvider` | Створює embedding adapter провайдера для memory/search | Поведінка memory embedding має належати плагіну провайдера | +| 41 | `buildReplayPolicy` | Повертає replay policy, яка керує обробкою стенограм для провайдера | Провайдеру потрібна власна політика стенограм (наприклад, видалення thinking blocks) | +| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення стенограми | Провайдеру потрібні власні переписування replay понад спільні helper-и компактизації | +| 43 | `validateReplayTurns` | Фінальна перевірка або переформатування ходів replay перед embedded runner | Транспорт провайдера потребує суворішої перевірки ходів після загальної санації | +| 44 | `onModelSelected` | Виконує side effects провайдера після вибору моделі | Провайдеру потрібна телеметрія або стан провайдера, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний плагін провайдера, а потім переходять до інших плагінів провайдерів із підтримкою хуків, -доки один із них фактично не змінить id моделі або transport/config. Це зберігає -працездатність shim-провайдерів alias/compat без необхідності для викликача знати, якому -комплектному плагіну належить переписування. Якщо жоден хук провайдера не перепише -підтримуваний запис конфігурації сімейства Google, комплектний нормалізатор конфігурації Google -все одно застосує це очищення сумісності. +підібраний плагін провайдера, а потім переходять до інших provider plugins, здатних +працювати з хуками, доки один із них справді не змінить model id або transport/config. Це зберігає +роботу alias/compat shim-ів провайдера без вимоги до виклику знати, який саме +вбудований плагін володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +запис конфігурації Google-family, вбудований нормалізатор конфігурації Google все одно застосовує +це очищення сумісності. -Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запиту, +Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, це інший клас розширення. Ці хуки призначені для поведінки провайдера, -яка все ще працює на звичайному циклі виведення OpenClaw. +яка все ще працює у звичайному циклі інференсу OpenClaw. ### Приклад провайдера @@ -774,115 +775,115 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - і `wrapStreamFn`, оскільки володіє forward-compat Claude 4.6, - підказками сімейства провайдера, рекомендаціями щодо відновлення auth, інтеграцією - кінцевої точки usage, придатністю prompt-cache, типовими значеннями конфігурації з урахуванням auth, - типовою/адаптивною політикою thinking Claude та специфічним для Anthropic формуванням потоку для + і `wrapStreamFn`, оскільки він володіє прямою сумісністю Claude 4.6, + підказками щодо сімейства провайдера, вказівками з ремонту auth, інтеграцією + endpoint-а usage, придатністю до prompt-cache, типовими значеннями конфігурації з урахуванням auth, + типовою/адаптивною політикою thinking для Claude та stream shaping, специфічним для Anthropic, для beta headers, `/fast` / `serviceTier` і `context1m`. - Допоміжні засоби потоку, специфічні для Claude в Anthropic, поки що залишаються у власному - публічному шві `api.ts` / `contract-api.ts` комплектного плагіна. Ця поверхня пакета + публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі - побудовники обгорток Anthropic замість розширення загального SDK навколо правил + builders wrapper-ів Anthropic замість розширення generic SDK навколо правил beta-header одного провайдера. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - оскільки володіє forward-compat GPT-5.4, прямою нормалізацією OpenAI + оскільки він володіє прямою сумісністю GPT-5.4, + прямою нормалізацією OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приглушенням Spark, синтетичними рядками списку OpenAI та політикою GPT-5 щодо thinking / - live-model; сімейство потоків `openai-responses-defaults` володіє - спільними native-обгортками OpenAI Responses для attribution headers, - `/fast`/`serviceTier`, verbosity тексту, native Codex web search, - формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses. -- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і + приховуванням Spark, синтетичними рядками списку OpenAI та політикою thinking / + live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє + спільними native wrappers OpenAI Responses для + attribution headers, `/fast`/`serviceTier`, verbosity тексту, native Codex web search, + формування payload 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`. + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати + заголовки запитів, метадані маршрутизації, reasoning patches і політику prompt-cache, специфічні для провайдера, поза ядром. + Його replay policy походить із сімейства + `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` + володіє proxy reasoning injection і пропусками для unsupported-model / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому - потрібні власний device login провайдера, поведінка fallback моделі, особливості - транскриптів Claude, обмін GitHub token -> Copilot token і власна - кінцева точка usage провайдера. + потрібні device login провайдера, поведінка fallback моделі, + особливості стенограм Claude, обмін токена GitHub на токен Copilot і власний endpoint usage провайдера. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він - все ще працює на транспорті ядра OpenAI, але володіє нормалізацією свого - transport/base URL, політикою fallback оновлення OAuth, типовим вибором транспорту, - синтетичними рядками каталогу Codex та інтеграцією кінцевої точки usage ChatGPT; він - спільно використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. -- Google AI Studio та Gemini CLI OAuth використовують `resolveDynamicModel`, + усе ще працює на транспорті ядра OpenAI, але володіє власною + нормалізацією transport/base URL, політикою fallback для оновлення OAuth, типовим вибором транспорту, + синтетичними рядками каталогу Codex і інтеграцією з endpoint-ом usage ChatGPT; він + використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. +- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки - сімейство replay `google-gemini` володіє fallback forward-compat Gemini 3.1, - native валідацією replay Gemini, санітаризацією bootstrap replay, режимом tagged - reasoning-output і зіставленням modern-model, тоді як сімейство потоків - `google-thinking` володіє нормалізацією корисного навантаження thinking Gemini; + сімейство replay `google-gemini` володіє fallback для прямої сумісності Gemini 3.1, + native validation replay для Gemini, санітарною обробкою bootstrap replay, режимом + tagged reasoning-output і зіставленням modern-model, тоді як + сімейство потоків `google-thinking` володіє нормалізацією payload thinking у Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і `fetchUsageSnapshot` для форматування токенів, розбору токенів і - підключення кінцевої точки quota. + підключення endpoint-а quota. - Anthropic Vertex використовує `buildReplayPolicy` через сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося - обмеженим id Claude, а не кожним транспортом `anthropic-messages`. + обмеженим Claude id, а не всім транспортом `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє - класифікацією помилок Bedrock для throttle/not-ready/context-overflow - у трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий - захист лише для Claude `anthropic-by-model`. + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він володіє + класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, + для трафіку Anthropic-on-Bedrock; його replay policy усе ще використовує той самий + guard лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini - через транспорти, сумісні з OpenAI, і потребують санітаризації - thought-signature Gemini без native валідації replay Gemini або - переписувань bootstrap. + через OpenAI-compatible transports і потребують санітарної обробки + thought-signature Gemini без native validation replay Gemini або + bootstrap rewrites. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє як семантикою - Anthropic-message, так і OpenAI-compatible; він зберігає скидання thinking-блоків - лише для Claude на стороні Anthropic, одночасно перевизначаючи режим reasoning - назад на native, а сімейство потоків `minimax-fast-mode` володіє переписуванням моделей - fast-mode на спільному шляху потоку. -- Moonshot використовує `catalog` плюс `wrapStreamFn`, оскільки все ще використовує спільний - транспорт OpenAI, але потребує нормалізації корисного навантаження thinking, що належить провайдеру; сімейство потоків - `moonshot-thinking` зіставляє config плюс стан `/think` з його - native двійковим корисним навантаженням thinking. + сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє і + семантикою Anthropic-message, і OpenAI-compatible; він зберігає видалення + thinking-block лише для Claude на стороні Anthropic, водночас перевизначаючи режим + reasoning output назад на native, а сімейство потоків `minimax-fast-mode` + володіє переписуванням fast-mode моделей на спільному шляху потоку. +- Moonshot використовує `catalog` і `wrapStreamFn`, оскільки він усе ще використовує спільний + транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; сімейство потоків + `moonshot-thinking` зіставляє config та стан `/think` на + native binary thinking payload. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, оскільки йому потрібні заголовки запиту, що належать провайдеру, - нормалізація корисного навантаження reasoning, підказки транскриптів Gemini та - керування TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає - ін’єкцію Kilo thinking на спільному шляху proxy stream, пропускаючи `kilo/auto` і - інші proxy model id, які не підтримують явні payload reasoning. + `isCacheTtlEligible`, оскільки йому потрібні власні заголовки запитів, + нормалізація payload reasoning, підказки щодо стенограм Gemini і gating cache-TTL для Anthropic; + сімейство потоків `kilocode-thinking` зберігає injection thinking Kilo + на спільному proxy stream path, водночас пропускаючи `kilo/auto` та + інші proxy model id, які не підтримують явні reasoning payloads. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє fallback GLM-5, - типовими значеннями `tool_stream`, UX двійкового thinking, зіставленням modern-model і обома - — auth usage та отриманням quota; сімейство потоків `tool-stream-default-on` зберігає - обгортку `tool_stream` із увімкненням за замовчуванням поза межами рукописного коду для кожного провайдера. + `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він володіє fallback для GLM-5, + типовими значеннями `tool_stream`, UX binary thinking, зіставленням modern-model та + і auth usage, і отриманням quota; сімейство потоків `tool-stream-default-on` тримає + wrapper `tool_stream` з типово увімкненим станом поза написаним вручну glue для окремих провайдерів. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - оскільки володіє нормалізацією native xAI Responses transport, переписуванням псевдонімів - Grok fast-mode, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, - повторним використанням fallback auth для інструментів, що належать плагіну, визначенням моделі Grok - з forward-compat і compat-патчами, що належать провайдеру, такими як профіль - схеми інструментів xAI, непідтримувані ключові слова схеми, native `web_search` і - декодування аргументів виклику інструментів із HTML-entity. + оскільки він володіє нормалізацією native xAI Responses transport, переписуванням + псевдонімів Grok fast-mode, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для інструментів, що належать плагіну, прямою сумісністю + при визначенні моделей Grok і compat patches провайдера, такими як профіль схем + інструментів xAI, непідтримувані ключові слова схеми, native `web_search` та декодування + аргументів викликів інструментів із HTML-entity. - 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` для свого текстового провайдера, а також спільні реєстрації розуміння медіа та генерації відео для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, оскільки їхня поведінка `/usage` - належить плагіну, навіть хоча виведення все ще працює через спільні транспорти. +- MiniMax і Xiaomi використовують `catalog` та хуки usage, оскільки їхня поведінка `/usage` + належить плагіну, хоча сам інференс усе ще виконується через спільні транспорти. -## Допоміжні засоби часу виконання +## Допоміжні засоби середовища виконання -Плагіни можуть отримати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -903,12 +904,12 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження TTS ядра для поверхонь файлів/голосових повідомлень. -- Використовує конфігурацію ядра `messages.tts` та вибір провайдера. -- Повертає PCM audio buffer + sample rate. Плагіни повинні виконувати resample/encode для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для селекторів голосів або потоків налаштування, що належать вендору. -- Списки голосів можуть містити розширеніші метадані, такі як locale, gender і теги personality для селекторів з урахуванням провайдера. -- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- `textToSpeech` повертає звичайний payload TTS ядра для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію `messages.tts` ядра та вибір провайдера. +- Повертає буфер PCM-аудіо + sample rate. Плагіни мають виконувати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для picker-ів голосів або потоків налаштування, що належать вендору. +- Списки голосів можуть містити багатші метадані, як-от locale, gender і personality tags для picker-ів, орієнтованих на провайдера. +- OpenAI та ElevenLabs сьогодні підтримують telephony. Microsoft — ні. Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. @@ -930,15 +931,15 @@ api.registerSpeechProvider({ Примітки: -- Тримайте політику TTS, fallback і доставку відповіді в ядрі. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. -- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один вендорний плагін може - володіти текстом, мовленням, зображенням і майбутніми медіапровайдерами, коли OpenClaw додає ці +- Зберігайте політику TTS, fallback і доставку відповідей у ядрі. +- Використовуйте speech providers для поведінки синтезу, що належить вендору. +- Застарілий ввід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один vendor-плагін може володіти + текстовими, мовними, графічними та майбутніми медіапровайдерами в міру того, як OpenClaw додає ці контракти можливостей. Для розуміння зображень/аудіо/відео плагіни реєструють один типізований -провайдер media-understanding замість загального key/value набору: +media-understanding provider замість універсального key/value bag: ```ts api.registerMediaUnderstandingProvider({ @@ -952,16 +953,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Тримайте оркестрацію, fallback, конфігурацію та підключення каналів у ядрі. -- Тримайте поведінку вендора в плагіні провайдера. +- Зберігайте оркестрацію, fallback, конфігурацію та прив’язку до каналів у ядрі. +- Зберігайте поведінку вендора в плагіні провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується того самого шаблону: - - ядро володіє контрактом можливості та допоміжним засобом часу виконання - - вендорні плагіни реєструють `api.registerVideoGenerationProvider(...)` +- Генерація відео вже дотримується тієї самої моделі: + - ядро володіє контрактом можливості та допоміжним засобом середовища виконання + - vendor-плагіни реєструють `api.registerVideoGenerationProvider(...)` - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів часу виконання media-understanding плагіни можуть викликати: +Для допоміжних засобів середовища виконання media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -976,8 +977,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо плагіни можуть використовувати або середовище часу виконання -media-understanding, або старіший псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або середовище виконання media-understanding, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -992,11 +993,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів. -- Повертає `{ text: undefined }`, коли результат транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу). +- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли не створено жодного виходу транскрипції (наприклад, пропущений/непідтримуваний ввід). - `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. -Плагіни також можуть запускати фонові виконання subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові запуски subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1011,13 +1012,13 @@ const result = await api.runtime.subagent.run({ Примітки: - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. -- OpenClaw враховує ці поля перевизначення лише для довірених викликаючих сторін. -- Для резервних запусків, що належать плагіну, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски subagent із недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять на fallback. +- OpenClaw враховує ці поля перевизначення лише для довірених викликачів. +- Для fallback запусків, що належать плагіну, оператори мають явно погодитися через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent від недовірених плагінів також працюють, але запити на перевизначення відхиляються замість тихого fallback. -Для веб-пошуку плагіни можуть споживати спільний допоміжний засіб часу виконання замість -звернення до підключення інструмента агента: +Для вебпошуку плагіни можуть споживати спільний helper середовища виконання замість +прямого звернення до прив’язки інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1033,14 +1034,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати провайдерів веб-пошуку через +Плагіни також можуть реєструвати провайдерів вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Тримайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. -- Використовуйте провайдерів веб-пошуку для вендор-специфічних транспортів пошуку. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Зберігайте вибір провайдера, визначення credentials і спільну семантику запитів у ядрі. +- Використовуйте web-search providers для транспортів пошуку, специфічних для вендора. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від wrapper-а інструмента агента. ### `api.runtime.imageGeneration` @@ -1055,12 +1056,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. -- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: перелічити доступних провайдерів генерації зображень та їхні можливості. ## HTTP-маршрути Gateway -Плагіни можуть відкривати HTTP-ендпоінти через `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP endpoint-и через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1078,31 +1079,31 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, керованих плагіном. +- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для auth/перевірки webhook, якою керує плагін. - `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. - `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. - `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` видалено і воно викличе помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. -- Маршрути плагінів повинні явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` тримайте лише на тому самому рівні auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області часу виконання оператора. Вони призначені для webhook/signature verification, керованих плагіном, а не для привілейованих допоміжних викликів 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 неявною admin-поверхнею. Якщо вашому маршруту потрібна поведінка лише для admin, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` видалено, і він спричинить помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. +- Маршрути плагінів мають явно оголошувати `auth`. +- Конфлікти точних `path + match` відхиляються, якщо не задано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Перекривані маршрути з різними рівнями `auth` відхиляються. Ланцюги fallthrough `exact`/`prefix` зберігайте лише на одному рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для webhook/signature verification, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. +- Маршрути `auth: "gateway"` працюють усередині runtime scope запиту Gateway, але ця область навмисно консервативна: + - bearer-auth на основі спільного секрету (`gateway.auth.mode = "token"` / `"password"`) зберігає runtime scopes маршрутів плагінів, зафіксовані на `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-поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час розробки плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: - `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. - `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. -- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` +- `openclaw/plugin-sdk/config-schema` для експорту Zod-схеми кореневого `openclaw.json` (`OpenClawSchema`). - Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1116,18 +1117,17 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного підключення setup/auth/reply/webhook. + `openclaw/plugin-sdk/webhook-ingress` для спільної логіки setup/auth/reply/webhook. `channel-inbound` — це спільний дім для debounce, зіставлення згадок, - допоміжних засобів inbound mention-policy, форматування envelope і - допоміжних засобів контексту inbound envelope. - `channel-setup` — це вузький шов setup для необов’язкового встановлення. - `setup-runtime` — це безпечна для часу виконання поверхня setup, яку використовують `setupEntry` / - відкладений запуск, включно з безпечними для імпорту адаптерами патчів setup. - `setup-adapter-runtime` — це env-aware шов адаптера налаштування облікового запису. - `setup-tools` — це невеликий шов допоміжних засобів CLI/archive/docs (`formatCliCommand`, + helper-ів політики вхідних згадок, форматування envelope і helper-ів контексту вхідного envelope. + `channel-setup` — це вузький шов setup з необов’язковим встановленням. + `setup-runtime` — це безпечна для середовища виконання поверхня setup, що використовується `setupEntry` / + відкладеним запуском, включно з безпечними для імпорту адаптерами patch setup. + `setup-adapter-runtime` — це env-aware шов адаптера setup облікового запису. + `setup-tools` — це малий шов допоміжних засобів CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, +- Підшляхи доменів, такі як `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1145,192 +1145,190 @@ 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` для спільних helper-ів runtime/config. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації користувацьких + команд Telegram і залишається доступним, навіть якщо поверхня контракту вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний шов text/markdown/logging, включно з - вилученням assistant-visible-text, допоміжними засобами рендерингу/розбиття markdown, допоміжними засобами редагування, - допоміжними засобами directive-tag і утилітами safe-text. -- Канальні шви, специфічні для погодження, повинні надавати перевагу одному контракту - `approvalCapability` у плагіні. Тоді ядро читає auth погодження, доставку, рендеринг, - native-routing і поведінку lazy native-handler через цю єдину можливість - замість змішування поведінки погодження з не пов’язаними полями плагіна. + `text-runtime` — це спільний шов тексту/markdown/logging, включно з + видаленням тексту, видимого помічнику, helper-ами рендерингу/розбиття markdown, редагування + helper-ів, helper-ів тегів директив і утилітами безпечного тексту. +- Approval-специфічні шви каналів мають віддавати перевагу одному контракту `approvalCapability` + у плагіні. Потім ядро читає auth approval, доставку, рендеринг, + native-routing і lazy native-handler behavior через цю одну можливість + замість змішування поведінки approval у не пов’язані поля плагіна. - `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як - shim сумісності для старіших плагінів. Новий код повинен імпортувати вужчі - загальні примітиви, а код репозиторію не повинен додавати нові імпорти shim. -- Внутрішні механізми комплектних розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише - підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати - публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, + shim сумісності для старіших плагінів. Новий код має імпортувати вужчі + загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього + shim. +- Внутрішня реалізація вбудованих розширень залишається приватною. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати + публічні entry point-ів репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js`, а також вузько спрямовані файли, такі як - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра чи з іншого розширення. -- Поділ точок входу репозиторію: - `/api.js` — це барабан helper/types, - `/runtime-api.js` — це барабан лише для часу виконання, - `/index.js` — це точка входу комплектного плагіна, - а `/setup-entry.js` — це точка входу setup-плагіна. -- Поточні приклади комплектних провайдерів: - - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких - як `wrapAnthropicProviderStream`, допоміжні засоби beta-header і парсинг `service_tier`. - - OpenAI використовує `api.js` для побудовників провайдерів, допоміжних засобів типових моделей і побудовників realtime-провайдерів. - - OpenRouter використовує `api.js` для свого побудовника провайдера, а також допоміжних засобів онбордингу/конфігурації, - тоді як `register.runtime.js` усе ще може повторно експортувати загальні - допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні точки входу, завантажені через facade, надають перевагу активному знімку конфігурації часу виконання, - якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли - OpenClaw ще не обслуговує знімок часу виконання. -- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір швів сумісності з брендуванням комплектних каналів усе ще існує. Розглядайте їх як - шви для підтримки комплектних плагінів/сумісності, а не як нові цілі імпорту для сторонніх рішень; - нові міжканальні контракти мають і далі потрапляти на загальні підшляхи `plugin-sdk/*` або в локальні барабани `api.js` / +- Розділення entry point-ів репозиторію: + `/api.js` — barrel helper-ів/типів, + `/runtime-api.js` — barrel лише для середовища виконання, + `/index.js` — entry вбудованого плагіна, + а `/setup-entry.js` — entry setup-плагіна. +- Поточні приклади вбудованих провайдерів: + - Anthropic використовує `api.js` / `contract-api.js` для helper-ів потоку Claude, таких + як `wrapAnthropicProviderStream`, helper-и beta-header і парсинг `service_tier`. + - OpenAI використовує `api.js` для builders провайдерів, helper-ів типових моделей і builders провайдерів realtime. + - OpenRouter використовує `api.js` для свого builder-а провайдера плюс helper-и onboarding/config, + тоді як `register.runtime.js` усе ще може повторно експортувати generic + helper-и `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні entry point-и, завантажені через facade, надають перевагу активному runtime snapshot конфігурації, + якщо він існує, а потім повертаються до визначеного config file на диску, якщо + OpenClaw ще не обслуговує runtime snapshot. +- Загальні shared primitives залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір compatibility seams допоміжних засобів вбудованих брендових каналів усе ще існує. + Розглядайте їх як шви підтримки вбудованих плагінів/сумісності, а не нові цілі імпорту для сторонніх розробників; нові міжканальні контракти все одно мають з’являтися на + загальних підшляхах `plugin-sdk/*` або в локальних barrels `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`. - Гейти дій повідомлень і допоміжні засоби message-id реакцій належать до +- Уникайте кореневого barrel-а `openclaw/plugin-sdk` у новому коді. +- Насамперед надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool є очікуваним контрактом для нових + вбудованих і зовнішніх плагінів. + Парсинг/зіставлення цілей має бути на `openclaw/plugin-sdk/channel-targets`. + Gating дій із повідомленнями та helper-и message-id для реакцій мають бути на `openclaw/plugin-sdk/channel-actions`. -- Допоміжні барабани, специфічні для комплектних розширень, не є стабільними за замовчуванням. Якщо - допоміжний засіб потрібен лише комплектному розширенню, тримайте його за локальним швом - `api.js` або `runtime-api.js` цього розширення замість того, щоб просувати його до +- Допоміжні barrels, специфічні для вбудованих розширень, за замовчуванням не є стабільними. Якщо + helper потрібен лише вбудованому розширенню, тримайте його за локальним + швом `api.js` або `runtime-api.js` розширення замість підвищення його до `openclaw/plugin-sdk/`. -- Нові спільні шви допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір цілей - належить до `openclaw/plugin-sdk/channel-targets`; внутрішні механізми, специфічні для каналу, - залишаються за локальним швом `api.js` або `runtime-api.js` плагіна-власника. +- Нові shared helper seams мають бути загальними, а не брендованими на честь каналу. Спільний парсинг цілей + має бути на `openclaw/plugin-sdk/channel-targets`; внутрішня реалізація, специфічна для каналу, + залишається за локальним швом `api.js` або `runtime-api.js` плагіна-власника. - Підшляхи, специфічні для можливостей, такі як `image-generation`, - `media-understanding` і `speech`, існують, тому що комплектні/нативні плагіни використовують - їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є - довгостроковим незмінним зовнішнім контрактом. + `media-understanding` і `speech`, існують, бо вбудовані/нативні плагіни використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є + довгостроковим замороженим зовнішнім контрактом. -## Схеми інструмента message +## Схеми інструмента повідомлень -Плагіни повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. +Плагіни мають володіти внесками у схему `describeMessageTool(...)`, специфічними для каналу. Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному ядрі. -Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через +Для спільних переносних фрагментів схеми повторно використовуйте загальні helper-и, експортовані через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для корисного навантаження у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованого payload картки +- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок +- `createMessageToolCardSchema()` для структурованих payload карток -Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному -коді цього плагіна замість просування до спільного SDK. +Якщо форма схеми має сенс лише для одного провайдера, визначайте її у вихідному коді +цього плагіна замість підвищення до спільного SDK. ## Визначення цілей каналу -Плагіни каналів повинні володіти семантикою цілей, специфічною для каналу. Тримайте спільний -outbound host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте +спільний outbound host загальним і використовуйте поверхню messaging adapter для правил провайдера: - `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль - слід розглядати як `direct`, `group` або `channel` до пошуку в директорії. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - ввід слід одразу спрямувати до визначення за схожим на id значенням замість пошуку в директорії. + слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи слід + вводу відразу перейти до визначення за схожістю на id замість пошуку в каталозі. - `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли - ядру потрібне фінальне визначення, що належить провайдеру, після нормалізації або - після промаху по директорії. + ядру потрібне фінальне визначення цілі, що належить провайдеру, після нормалізації або + після промаху в каталозі. - `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, - специфічною для провайдера, коли ціль уже визначено. + специфічною для провайдера, після визначення цілі. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають прийматися до - пошуку серед peer/group. -- Використовуйте `looksLikeId` для перевірок на кшталт «розглядати це як явний/native target id». -- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для провайдера, а не для - широкого пошуку в директорії. -- Тримайте native id провайдера, такі як chat id, thread id, JID, handle і room id, - у значеннях `target` або параметрах, специфічних для провайдера, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для категорійних рішень, які мають відбуватися до + пошуку серед контактів/груп. +- Використовуйте `looksLikeId` для перевірок «розглядати це як явний/native target id». +- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для + широкого пошуку в каталозі. +- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle та room + id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Директорії на основі конфігурації +## Каталоги на основі конфігурації -Плагіни, які виводять записи директорії з конфігурації, повинні тримати цю логіку в -плагіні та повторно використовувати спільні допоміжні засоби з +Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в +плагіні та повторно використовувати спільні helper-и з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні контакти/групи на основі конфігурації, наприклад: -- DM peer, керовані allowlist -- налаштовані карти каналів/груп -- статичні fallback директорії в межах облікового запису +- DM-контакти, керовані allowlist +- налаштовані відповідності каналів/груп +- статичні fallback-и каталогів із прив’язкою до облікового запису -Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: +Спільні helper-и в `directory-runtime` обробляють лише загальні операції: -- фільтрацію запиту +- фільтрацію запитів - застосування ліміту -- дедуплікацію/нормалізацію +- helper-и дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Інспекція облікового запису, специфічна для каналу, і нормалізація id мають залишатися в -реалізації плагіна. +Інспекція облікового запису та нормалізація id, специфічні для каналу, мають залишатися +в реалізації плагіна. ## Каталоги провайдерів -Плагіни провайдерів можуть визначати каталоги моделей для виведення за допомогою +Плагіни провайдерів можуть визначати каталоги моделей для інференсу за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: - `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдерів +- `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли плагін володіє model id провайдера, типовими -значеннями base URL або метаданими моделей, що залежать від auth. +Використовуйте `catalog`, коли плагін володіє model id, базовими значеннями `baseUrl` +або метаданими моделей, що залежать від auth, специфічними для провайдера. -`catalog.order` визначає, коли каталог плагіна зливається відносно вбудованих -неявних провайдерів OpenClaw: +`catalog.order` контролює, коли каталог плагіна об’єднується відносно +вбудованих неявних провайдерів OpenClaw: -- `simple`: прості провайдери на основі API-key або env -- `profile`: провайдери, які з’являються, коли існують auth-профілі -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів +- `simple`: провайдери зі звичайним API-key або керовані env +- `profile`: провайдери, які з’являються, коли існують auth profiles +- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів Пізніші провайдери перемагають у разі колізії ключів, тож плагіни можуть навмисно -перевизначати вбудований запис провайдера з тим самим id провайдера. +перевизначати вбудований запис провайдера з тим самим ідентифікатором. Сумісність: -- `discovery` все ще працює як застарілий псевдонім -- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` +- `discovery` досі працює як застарілий синонім +- якщо зареєстровані і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Лише читання для перевірки каналу +## Канальне інспектування лише для читання Якщо ваш плагін реєструє канал, надавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях часу виконання. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. +- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що credentials + повністю матеріалізовані, і швидко завершуватися помилкою, коли обов’язкові секрети відсутні. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config - repair, не повинні потребувати матеріалізації облікових даних часу виконання лише для + для відновлення, не повинні вимагати матеріалізації runtime credentials лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: -- Повертає лише описовий стан облікового запису. -- Зберігає `enabled` і `configured`. -- Включає поля джерела/стану облікових даних, якщо це доречно, наприклад: +- Повертайте лише описовий стан облікового запису. +- Зберігайте `enabled` і `configured`. +- Додавайте поля джерела/статусу credentials, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для того, щоб повідомити про доступність - лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). -- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але - недоступні в поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі тільки читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але + він недоступний у поточному шляху команди. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість збою або помилкового позначення облікового запису як неналаштованого. -## Package packs +## Пакети pack Каталог плагіна може містити `package.json` з `openclaw.extensions`: @@ -1344,66 +1342,63 @@ outbound host загальним і використовуйте поверхн } ``` -Кожен запис стає плагіном. Якщо pack перелічує кілька розширень, id плагіна +Кожен запис стає плагіном. Якщо pack перелічує кілька розширень, ідентифікатор плагіна стає `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 dependencies у середовищі виконання). Тримайте дерева залежностей плагіна як -«чисті JS/TS» і уникайте пакетів, що потребують збірки через `postinstall`. +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies у runtime). Підтримуйте дерева залежностей плагінів «чистими JS/TS» й уникайте пакетів, які потребують складання через `postinstall`. Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або -коли плагін каналу ввімкнено, але він ще не налаштований, він завантажує `setupEntry` -замість повної точки входу плагіна. Це робить запуск і налаштування легшими, -коли основна точка входу плагіна також підключає інструменти, хуки або інший код, -потрібний лише під час виконання. +Коли OpenClaw потребує поверхонь setup для вимкненого channel plugin, або +коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повного entry плагіна. Це робить запуск і налаштування легшими, +коли основний entry плагіна також підключає інструменти, хуки або інший код лише для runtime. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести плагін каналу на той самий шлях `setupEntry` під час -фази запуску gateway до початку прослуховування, навіть якщо канал уже налаштований. +може переводити channel plugin на той самий шлях `setupEntry` під час фази +запуску gateway до початку прослуховування, навіть коли канал уже налаштований. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup -має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: +до того, як gateway почне прослуховування. На практиці це означає, що entry setup +має реєструвати всі можливості каналу, від яких залежить запуск, наприклад: - саму реєстрацію каналу -- будь-які HTTP-маршрути, які повинні бути доступні до того, як gateway почне прослуховування -- будь-які gateway methods, інструменти або сервіси, які мають існувати в тому самому вікні +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому ж вікні часу -Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште плагін із типовою поведінкою й дозвольте OpenClaw завантажувати -повну точку входу під час запуску. +Якщо ваш повний entry усе ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте +цей прапорець. Залишайте плагін на типовій поведінці й дозвольте OpenClaw завантажити +повний entry під час запуску. -Комплектні канали також можуть публікувати допоміжні засоби лише для setup на поверхні контракту, які ядро -може використовувати до завантаження повного середовища часу виконання каналу. Поточна -поверхня просування setup така: +Вбудовані канали також можуть публікувати helper-и поверхні контракту лише для setup, до яких ядро +може звертатися до завантаження повного runtime каналу. Поточна поверхня просування setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію -однокористувацького каналу до `channels..accounts.*` без завантаження повної точки входу плагіна. -Поточний комплектний приклад — Matrix: він переносить лише ключі auth/bootstrap у -іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно перенести застарілу конфігурацію одноканального +каналу в `channels..accounts.*` без завантаження повного entry плагіна. +Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap у +іменований promoted account, коли іменовані облікові записи вже існують, і може зберегти +налаштований non-canonical ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів setup зберігають ледаче виявлення поверхні контракту комплектного плагіна. Час -імпорту залишається легким; поверхня просування завантажується лише при першому використанні -замість повторного входу в запуск комплектного каналу під час імпорту модуля. +Ці адаптери patch setup зберігають ліниве виявлення поверхні контракту вбудованих плагінів. Час імпорту +залишається малим; поверхня просування завантажується лише під час першого використання замість +повторного входу у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають gateway RPC methods, тримайте їх на +Коли ці поверхні запуску включають gateway RPC methods, зберігайте їх на префіксі, специфічному для плагіна. Простори імен admin ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -до `operator.admin`, навіть якщо плагін запитує вужчу область. +як `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -1422,8 +1417,8 @@ outbound host загальним і використовуйте поверхн ### Метадані каталогу каналів -Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. +Плагіни каналів можуть рекламувати метадані setup/discovery через `openclaw.channel` та +підказки встановлення через `openclaw.install`. Це дозволяє ядру не мати власних даних каталогу. Приклад: @@ -1451,22 +1446,22 @@ outbound host загальним і використовуйте поверхн } ``` -Корисні поля `openclaw.channel`, крім мінімального прикладу: +Корисні поля `openclaw.channel` поза мінімальним прикладом: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначення тексту посилання для посилання на документацію -- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має перевершувати +- `docsLabel`: перевизначити текст посилання на документацію +- `preferOver`: ідентифікатори нижчопріоритетних плагінів/каналів, які цей запис каталогу має випереджати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору -- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень форматування вихідних повідомлень -- `exposure.configured`: приховує канал із поверхонь списків налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних селекторів setup/configure, якщо встановлено `false` +- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо вихідного форматування +- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо значення `false` +- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо значення `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target +- `showConfigured` / `showInSetup`: застарілі синоніми все ще приймаються для сумісності; надавайте перевагу `exposure` +- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надавати перевагу пошуку сесії під час визначення announce targets -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). +OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). Помістіть JSON-файл в одне з таких місць: - `~/.openclaw/mpm/plugins.json` @@ -1474,18 +1469,18 @@ OpenClaw також може зливати **зовнішні каталоги - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один або кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має -містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. +один або кілька JSON-файлів (розділення комою/крапкою з комою/`PATH`). Кожен файл має +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі синоніми ключа `"entries"`. -## Плагіни контекстного рушія +## Плагіни рушія контексту -Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly -і compaction. Реєструйте їх зі свого плагіна через +Плагіни рушія контексту володіють оркестрацією контексту сесії для ingest, assemble +і compact. Реєструйте їх у своєму плагіні через `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті або хуки. +конвеєр контексту, а не просто додати memory search або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1513,8 +1508,8 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом compaction, залиште `compact()` -реалізованим і явно делегуйте його: +Якщо ваш рушій **не** володіє алгоритмом компактизації, залишайте `compact()` +реалізованим і явно делегуйте її: ```ts import { @@ -1552,43 +1547,44 @@ export default function (api) { ## Додавання нової можливості Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний внутрішній доступ. Додайте відсутню можливість. +систему плагінів приватним втручанням. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, злиття конфігурації, - життєвий цикл, семантика для каналів і форма допоміжного засобу часу виконання. -2. додайте типізовані поверхні реєстрації/часу виконання плагіна + Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, об’єднання конфігурації, + життєвий цикл, семантика для каналів і форма допоміжного засобу середовища виконання. +2. додайте типізовані поверхні реєстрації/середовища виконання плагіна Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. 3. підключіть споживачів ядра + каналів/функцій Канали та плагіни функцій мають споживати нову можливість через ядро, - а не імпортувати реалізацію вендора напряму. + а не імпортувати реалізацію вендора безпосередньо. 4. зареєструйте реалізації вендорів - Потім вендорні плагіни реєструють свої бекенди для цієї можливості. -5. додайте покриття контрактів - Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. + Потім vendor-плагіни реєструють свої бекенди для цієї можливості. +5. додайте контрактне покриття + Додайте тести, щоб володіння та форма реєстрації залишалися явними з часом. -Так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до світогляду -одного провайдера. Конкретний перелік файлів і готовий приклад див. у [Cookbook можливостей](/uk/plugins/architecture). +Саме так OpenClaw залишається системою з чіткою позицією, не стаючи жорстко прив’язаною до +світогляду одного провайдера. Див. [Практичний посібник з можливостей](/uk/plugins/architecture) +для конкретного контрольного списку файлів і повного прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих -поверхонь разом: +Коли ви додаєте нову можливість, реалізація зазвичай має охоплювати ці +поверхні разом: -- типи контрактів ядра в `src//types.ts` -- runner/допоміжний засіб часу виконання ядра в `src//runtime.ts` -- поверхня реєстрації API плагіна в `src/plugins/types.ts` -- підключення реєстру плагінів у `src/plugins/registry.ts` -- відкриття середовища часу виконання плагіна в `src/plugins/runtime/*`, коли плагіни функцій/каналів - повинні його споживати -- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` +- типи контракту ядра в `src//types.ts` +- runner/helper середовища виконання ядра в `src//runtime.ts` +- поверхню реєстрації API плагіна в `src/plugins/types.ts` +- прив’язку реєстру плагінів у `src/plugins/registry.ts` +- експонування runtime плагіна в `src/plugins/runtime/*`, коли плагіни функцій/каналів + мають її споживати +- helper-и capture/test у `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` -- документація для операторів/плагінів у `docs/` +- документацію для операторів/плагінів у `docs/` -Якщо якоїсь із цих поверхонь бракує, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1619,7 +1615,7 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Шаблон тесту контракту: +Шаблон контрактного тесту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1628,6 +1624,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: - ядро володіє контрактом можливості + оркестрацією -- вендорні плагіни володіють реалізаціями вендора -- плагіни функцій/каналів споживають допоміжні засоби часу виконання -- тести контрактів зберігають явність володіння +- vendor-плагіни володіють реалізаціями вендора +- плагіни функцій/каналів споживають допоміжні засоби середовища виконання +- контрактні тести зберігають явність володіння diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index d0463135b..08de5ff75 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,75 +1,75 @@ --- read_when: - Ви створюєте плагін OpenClaw - - Вам потрібно постачати schema конфігурації плагіна або налагодити помилки валідації плагіна -summary: Вимоги до маніфесту плагіна та JSON schema (сувора валідація конфігурації) + - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна +summary: Вимоги до маніфесту плагіна та JSON Schema (сувора валідація конфігурації) title: Маніфест плагіна x-i18n: - generated_at: "2026-04-06T18:56:33Z" + generated_at: "2026-04-08T18:09:11Z" model: gpt-5.4 provider: openai - source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a + source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a source_path: plugins/manifest.md workflow: 15 --- # Маніфест плагіна (openclaw.plugin.json) -Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**. +Ця сторінка стосується лише **нативного маніфесту плагіна OpenClaw**. -Сумісні макети пакетів описані в [Пакети плагінів](/uk/plugins/bundles). +Сумісні макети bundle описано в розділі [Пакети плагінів](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати bundle використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонентів Claude +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` або типовий макет компонента Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію -за schema `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію +за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом з оголошеними -коренями Skills, коренями команд Claude, типовими значеннями `settings.json` пакета Claude, -типовими значеннями LSP пакета Claude та підтримуваними наборами хуків, якщо макет відповідає +Для сумісних bundle OpenClaw зараз читає метадані bundle разом з оголошеними +коренями Skills, коренями команд Claude, значеннями за замовчуванням `settings.json` у Claude bundle, +значеннями за замовчуванням LSP у Claude bundle та підтримуваними пакетами хукiв, коли макет відповідає очікуванням рантайму OpenClaw. -Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у +Кожен нативний плагін OpenClaw **повинен** постачати файл `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються -помилками плагіна та блокують валідацію конфігурації. +**без виконання коду плагіна**. Відсутні або недійсні маніфести вважаються +помилками плагіна і блокують валідацію конфігурації. -Дивіться повний посібник із системи плагінів: [Плагіни](/uk/tools/plugin). -Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: +Дивіться повний посібник по системі плагінів: [Плагіни](/uk/tools/plugin). +Щодо нативної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує до завантаження коду -вашого плагіна. +`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням +коду вашого плагіна. Використовуйте його для: - ідентифікації плагіна - валідації конфігурації -- метаданих автентифікації та онбордингу, які мають бути доступні без запуску рантайму - плагіна +- метаданих автентифікації та онбордингу, які мають бути доступні без запуску + рантайму плагіна - метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження рантайму плагіна -- метаданих володіння скороченими сімействами моделей, які мають автоматично активувати +- скорочених метаданих про належність до сімейств моделей, які мають автоматично активувати плагін до завантаження рантайму -- статичних знімків володіння можливостями, що використовуються для сумісної в’язки bundled-плагінів і - перевірки контрактів -- метаданих конфігурації каналів, які мають об’єднуватися в поверхні каталогу та валідації +- статичних знімків належності можливостей, що використовуються для вбудованої compat-обв’язки та + покриття контрактів +- метаданих конфігурації для конкретних каналів, які мають зливатися в поверхні каталогу й валідації без завантаження рантайму - підказок UI для конфігурації Не використовуйте його для: - реєстрації поведінки рантайму -- оголошення кодових entrypoint-ів +- оголошення кодових entrypoint - метаданих встановлення npm -Це належить коду вашого плагіна та `package.json`. +Для цього призначені код вашого плагіна та `package.json`. ## Мінімальний приклад @@ -90,7 +90,7 @@ OpenClaw також автоматично виявляє ці макети па { "id": "openrouter", "name": "OpenRouter", - "description": "Плагін провайдера OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,6 +100,9 @@ OpenClaw також автоматично виявляє ці макети па "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, + "providerAuthAliases": { + "openrouter-coding": "openrouter" + }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, @@ -108,19 +111,19 @@ OpenClaw також автоматично виявляє ці макети па "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Ключ API OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Ключ API OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Ключ API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -137,56 +140,57 @@ OpenClaw також автоматично виявляє ці макети па } ``` -## Довідка щодо полів верхнього рівня +## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що це означає | | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Канонічний id плагіна. Саме цей id використовується в `plugins.entries.`. | +| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. | -| `enabledByDefault` | Ні | `true` | Позначає bundled-плагін як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id плагіна. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | | `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей плагін. | -| `modelSupport` | Ні | `object` | Власні для маніфесту метадані скорочених сімейств моделей, які використовуються для автозавантаження плагіна до рантайму. | -| `cliBackends` | Ні | `string[]` | Id backend-ів інференсу CLI, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | -| `providerAuthEnvVars` | Ні | `Record` | Легкі env-метадані автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | -| `channelEnvVars` | Ні | `Record` | Легкі env-метадані каналів, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити стандартні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для пікерів онбордингу, визначення preferred-provider та простої в’язки прапорців CLI. | -| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search та володіння інструментами. | -| `channelConfigs` | Ні | `Record` | Власні для маніфесту метадані конфігурації каналів, які об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. | +| `modelSupport` | Ні | `object` | Скорочені метадані про сімейства моделей, що належать маніфесту та використовуються для автозавантаження плагіна до запуску рантайму. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для інференсу в CLI, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | +| `providerAuthEnvVars` | Ні | `Record` | Легкі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding-провайдер, який використовує той самий API-ключ і профілі автентифікації базового провайдера. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані env для каналів, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити типові помічники старту/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення preferred provider і простої обв’язки CLI-прапорців. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search та належності інструментів. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту та зливаються в поверхні виявлення й валідації до завантаження рантайму. | | `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | -| `name` | Ні | `string` | Людинозрозуміла назва плагіна. | -| `description` | Ні | `string` | Короткий опис, який показується на поверхнях плагіна. | -| `version` | Ні | `string` | Інформаційна версія плагіна. | -| `uiHints` | Ні | `Record` | UI-мітки, placeholders та підказки щодо чутливості для полів конфігурації. | +| `name` | Ні | `string` | Зрозуміла людині назва плагіна. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. | +| `version` | Ні | `string` | Інформаційна версія плагіна. | +| `uiHints` | Ні | `Record` | Підписи UI, заповнювачі та підказки чутливості для полів конфігурації. | -## Довідка щодо `providerAuthChoices` +## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження рантайму провайдера. +OpenClaw читає це до завантаження рантайму провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| -------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого потрібно спрямувати запит. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується онбордингом і потоками CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо опущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для пікера. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних пікерах, керованих асистентом. | -| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у пікерах асистента, але залишає можливість ручного вибору через CLI. | -| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей замінний варіант. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для цієї групи, видима користувачеві. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має відображатися цей варіант. Якщо опущено, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно диспетчеризувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних селекторах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Підпис для цієї групи, видимий користувачу. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, за замовчуванням використовується `["text-inference"]`. | -## Довідка щодо `uiHints` +## Довідник `uiHints` `uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. @@ -194,8 +198,8 @@ OpenClaw зчитує це до завантаження рантайму про { "uiHints": { "apiKey": { - "label": "Ключ API", - "help": "Використовується для запитів OpenRouter", + "label": "API key", + "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -205,19 +209,19 @@ OpenClaw зчитує це до завантаження рантайму про Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теги. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| Поле | Тип | Що це означає | +| ------------- | ---------- | ------------------------------------ | +| `label` | `string` | Підпис поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | -## Довідка щодо `contracts` +## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -зчитати без імпорту рантайму плагіна. +Використовуйте `contracts` лише для статичних метаданих про належність можливостей, які OpenClaw може +читати без імпорту рантайму плагіна. ```json { @@ -237,19 +241,19 @@ OpenClaw зчитує це до завантаження рантайму про Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ---------------------------------------------------------- | -| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей плагін. | -| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime transcription, якими володіє цей плагін. | -| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime voice, якими володіє цей плагін. | -| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. | -| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. | -| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. | -| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. | -| `webSearchProviders` | `string[]` | Id провайдерів web-search, якими володіє цей плагін. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін для bundled-перевірок контрактів. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ----------------------------------------------------------- | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів speech, якими володіє цей плагін. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-transcription, якими володіє цей плагін. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime-voice, якими володіє цей плагін. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей плагін. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей плагін. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей плагін. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей плагін. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web-search, якими володіє цей плагін. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін для перевірок вбудованих контрактів. | -## Довідка щодо `channelConfigs` +## Довідник `channelConfigs` Використовуйте `channelConfigs`, коли плагіну каналу потрібні легкі метадані конфігурації до завантаження рантайму. @@ -267,12 +271,12 @@ OpenClaw зчитує це до завантаження рантайму про }, "uiHints": { "homeserverUrl": { - "label": "URL homeserver-а", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Підключення до Matrix homeserver-а", + "description": "Matrix homeserver connection", "preferOver": ["matrix-legacy"] } } @@ -281,18 +285,19 @@ OpenClaw зчитує це до завантаження рантайму про Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові UI-мітки/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що додається до поверхонь пікера та інспекції, коли метадані рантайму ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | -| `preferOver` | `string[]` | Id застарілих або менш пріоритетних плагінів, які цей канал має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, що зливається в поверхні селектора та перегляду, коли метадані рантайму ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | +| `preferOver` | `string[]` | Застарілі або менш пріоритетні ідентифікатори плагінів, які цей канал має перевершувати в поверхнях вибору. | -## Довідка щодо `modelSupport` +## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за -скороченими id моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження рантайму плагіна. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш плагін провайдера з +скорочених ідентифікаторів моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до того, як завантажиться +рантайм плагіна. ```json { @@ -305,72 +310,73 @@ OpenClaw зчитує це до завантаження рантайму про OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику +- явні посилання `provider/model` використовують метадані маніфесту `providers`, яким належить модель - `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один неbundled-плагін і один bundled-плагін, перемагає неbundled-плагін -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера +- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований + плагін +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як -володіння можливостями. +належність можливостей. -## Маніфест у порівнянні з package.json +## Маніфест і package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та UI-підказки, які мають існувати до запуску коду плагіна | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint-ів, обмежень встановлення, налаштування або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, entry-файлів або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw повинен знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, entry file або поведінки встановлення npm, помістіть це в `package.json` -### Поля package.json, які впливають на виявлення +### Поля package.json, що впливають на виявлення -Деякі метадані плагіна до запуску рантайму навмисно зберігаються в `package.json` у блоці +Деякі метадані плагіна до запуску рантайму навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує власні entrypoint-и плагіна. | -| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналів. | -| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже хтось увійшов у систему?» без завантаження повного рантайму каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення bundled-плагінів і зовнішньо опублікованих плагінів. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із semver-межою на кшталт `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled-плагіна, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`| Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. | +| Поле | Що це означає | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує нативні entrypoint плагіна. | +| `openclaw.setupEntry` | Полегшений entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. | +| `openclaw.channel` | Легкі метадані каталогу каналів, як-от підписи, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання «чи вже є хоч один активний вхід?» без завантаження повного рантайму каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого плагіна, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. | -`openclaw.install.minHostVersion` перевіряється під час встановлення та -завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають -плагін на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення +призводять до пропуску плагіна на старіших хостах. -`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно -не робить довільні зламані конфігурації придатними для встановлення. Наразі воно лише дозволяє -процесам встановлення відновлюватися після конкретних застарілих збоїв оновлення bundled-плагіна, таких як -відсутній шлях bundled-плагіна або застарілий запис `channels.` для цього самого -bundled-плагіна. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким механізмом. Це +не робить довільні пошкоджені конфігурації придатними до встановлення. Зараз це лише дозволяє +потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованих плагінів, таких як +відсутній шлях до вбудованого плагіна або застарілий запис `channels.` для того самого +вбудованого плагіна. Непов’язані помилки конфігурації все одно блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: ```json @@ -387,12 +393,13 @@ bundled-плагіна. Непов’язані помилки конфігур } ``` -Використовуйте це, коли потоки setup, doctor або configured-state потребують -легкої yes/no перевірки автентифікації до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою -функцією, яка читає лише збережений стан; не спрямовуйте його через повний barrel рантайму каналу. +Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевої перевірки автентифікації так/ні +до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою +функцією, яка читає лише збережений стан; не спрямовуйте її через повний +barrel рантайму каналу. -`openclaw.channel.configuredState` має таку саму форму для легких перевірок -configured-state лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -408,61 +415,64 @@ configured-state лише через env: } ``` -Використовуйте це, коли канал може відповісти про configured-state на основі env або інших невеликих -вхідних даних без рантайму. Якщо перевірка потребує повного визначення конфігурації або реального -рантайму каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`. +Використовуйте це, коли канал може визначити налаштований стан через env або інші невеликі +нерантаймові вхідні дані. Якщо перевірка потребує повного визначення конфігурації або справжнього +рантайму каналу, залишайте цю логіку в хуку плагіна `config.hasConfiguredState`. ## Вимоги до JSON Schema - **Кожен плагін повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня schema є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Schema проходять валідацію під час читання/запису конфігурації, а не під час рантайму. +- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі. ## Поведінка валідації -- Невідомі ключі `channels.*` — це **помилки**, якщо тільки id каналу не оголошено - маніфестом плагіна. +- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошено + в маніфесті плагіна. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **виявлювані** id плагінів. Невідомі id — це **помилки**. -- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи schema, + повинні посилатися на **доступні для виявлення** ідентифікатори плагінів. Невідомі ідентифікатори — це **помилки**. +- Якщо плагін установлено, але він має пошкоджений або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна. -- Якщо конфігурація плагіна існує, але плагін **вимкнено**, конфігурація зберігається, і - у Doctor та журналах з’являється **попередження**. +- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, а в + Doctor і журналах з’являється **попередження**. -Дивіться [Довідник із конфігурації](/uk/gateway/configuration) для повної schema `plugins.*`. +Дивіться [Довідник з конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки -- Маніфест **обов’язковий для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. -- Рантайм усе одно завантажує модуль плагіна окремо; маніфест використовується лише для - виявлення + валідації. -- Власні маніфести аналізуються за допомогою JSON5, тому коментарі, кінцеві коми та - неукладені в лапки ключі приймаються, якщо підсумкове значення все ще є об’єктом. -- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте додавання +- Маніфест **обов’язковий для нативних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. +- Рантайм усе одно окремо завантажує модуль плагіна; маніфест призначений лише для + виявлення та валідації. +- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, завершальні коми та + незакавычені ключі приймаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання тут власних ключів верхнього рівня. - `providerAuthEnvVars` — це легкий шлях метаданих для перевірок автентифікації, валідації - env-marker та подібних поверхонь автентифікації провайдера, які не повинні запускати рантайм плагіна + env-маркерів і подібних поверхонь автентифікації провайдера, які не повинні запускати рантайм плагіна лише для перевірки назв env. -- `channelEnvVars` — це легкий шлях метаданих для shell-env fallback, підказок setup +- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати автентифікацію + іншого провайдера: env vars, профілі автентифікації, автентифікацію на основі конфігурації та + варіант онбордингу з API-ключем, без жорсткого кодування цього зв’язку в core. +- `channelEnvVars` — це легкий шлях метаданих для fallback через shell env, запитів setup та подібних поверхонь каналів, які не повинні запускати рантайм плагіна лише для перевірки назв env. -- `providerAuthChoices` — це легкий шлях метаданих для пікерів варіантів автентифікації, - визначення `--auth-choice`, мапінгу preferred-provider і простої реєстрації прапорців CLI - під час онбордингу до завантаження рантайму провайдера. Метадані wizard рантайму, - які потребують коду провайдера, див. у +- `providerAuthChoices` — це легкий шлях метаданих для селекторів варіантів автентифікації, + визначення `--auth-choice`, зіставлення preferred provider і простої реєстрації + прапорців CLI онбордингу до завантаження рантайму провайдера. Для метаданих + майстра рантайму, які потребують коду провайдера, дивіться [Хуки рантайму провайдера](/uk/plugins/architecture#provider-runtime-hooks). - Ексклюзивні типи плагінів вибираються через `plugins.slots.*`. - `kind: "memory"` вибирається через `plugins.slots.memory`. - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` - (типово: вбудований `legacy`). -- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо - плагіну вони не потрібні. -- Якщо ваш плагін залежить від native-модулів, задокументуйте кроки збирання та будь-які + (за замовчуванням: вбудований `legacy`). +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо + плагін їх не потребує. +- Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Пов’язані матеріали +## Пов’язане - [Створення плагінів](/uk/plugins/building-plugins) — початок роботи з плагінами - [Архітектура плагінів](/uk/plugins/architecture) — внутрішня архітектура -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник з Plugin SDK +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник по Plugin SDK diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index efa255169..8b98532c4 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -7,27 +7,27 @@ sidebarTitle: Provider Plugins summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw title: Створення плагінів постачальників x-i18n: - generated_at: "2026-04-06T15:31:24Z" + generated_at: "2026-04-08T18:09:13Z" model: gpt-5.4 provider: openai - source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 + source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Створення плагінів постачальників -У цьому посібнику покроково розглядається створення плагіна постачальника, який додає до OpenClaw постачальника моделей -(LLM). Наприкінці ви матимете постачальника з каталогом моделей, -автентифікацією через API-ключ і динамічним визначенням моделей. +Цей посібник покроково пояснює, як створити плагін постачальника, який додає +до OpenClaw постачальника моделей (LLM). Наприкінці у вас буде постачальник із каталогом моделей, +автентифікацією через API key та динамічним визначенням моделей. Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Getting Started](/uk/plugins/building-plugins) про базову структуру - пакета й налаштування маніфесту. + [Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою + структурою пакета та налаштуванням маніфесту. -## Покрокове проходження +## Покроковий приклад @@ -65,6 +65,9 @@ x-i18n: "providerAuthEnvVars": { "acme-ai": ["ACME_AI_API_KEY"] }, + "providerAuthAliases": { + "acme-ai-coding": "acme-ai" + }, "providerAuthChoices": [ { "provider": "acme-ai", @@ -87,16 +90,17 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов'язковим - і дає змогу OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими id моделей - на кшталт `acme-large` ще до появи runtime hooks. Якщо ви публікуєте - постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build` - обов'язкові в `package.json`. + облікові дані без завантаження runtime вашого плагіна. Додайте `providerAuthAliases`, + якщо варіант постачальника має повторно використовувати автентифікацію іншого ідентифікатора постачальника. `modelSupport` + необов’язковий і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника зі скорочених + ідентифікаторів моделей, таких як `acme-large`, ще до появи runtime hooks. Якщо ви публікуєте + постачальника у ClawHub, ці поля `openclaw.compat` і `openclaw.build` + обов’язкові в `package.json`. - Мінімальний постачальник потребує `id`, `label`, `auth` і `catalog`: + Мінімальному постачальнику потрібні `id`, `label`, `auth` і `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -171,8 +175,8 @@ x-i18n: `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Для вбудованих постачальників, які реєструють лише одного текстового постачальника з - автентифікацією через API-ключ і одним runtime на основі каталогу, віддавайте перевагу вужчому + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією через API key + плюс один runtime на основі каталогу, віддавайте перевагу вужчому допоміжному засобу `defineSingleProviderPluginEntry(...)`: ```typescript @@ -208,24 +212,24 @@ x-i18n: }); ``` - Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми й - типову модель агента під час онбордингу, використовуйте готові допоміжні засоби з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі допоміжні засоби — - це `createDefaultModelPresetAppliers(...)`, + Якщо ваш потік автентифікації також має оновлювати `models.providers.*`, aliases і + модель агента за замовчуванням під час онбордингу, використовуйте готові helper-функції з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі helper-функції: + `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативний endpoint постачальника підтримує блоки streamed usage на - звичайному transport `openai-completions`, віддавайте перевагу спільним допоміжним засобам каталогу з - `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко закодованим перевіркам - id постачальника. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з мапи можливостей endpoint, тому нативні endpoint у стилі Moonshot/DashScope - також підключаються, навіть коли плагін використовує власний id постачальника. + Якщо власний endpoint постачальника підтримує потокові блоки використання на + звичайному транспорті `openai-completions`, віддавайте перевагу спільним helper-функціям каталогу з + `openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок + ідентифікатора постачальника. `supportsNativeStreamingUsageCompat(...)` і + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з карти можливостей endpoint, тож власні endpoint Moonshot/DashScope-типу + також можуть бути увімкнені, навіть якщо плагін використовує власний ідентифікатор постачальника. - Якщо ваш постачальник приймає довільні id моделей (як проксі або маршрутизатор), + Якщо ваш постачальник приймає довільні ідентифікатори моделей (як проксі чи маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -248,16 +252,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - прогрівання — `resolveDynamicModel` буде запущено знову після його завершення. + прогріву — після завершення `resolveDynamicModel` буде запущено знову. - Більшості постачальників достатньо `catalog` + `resolveDynamicModel`. Додавайте hooks - поступово, у міру того як цього потребуватиме ваш постачальник. + Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks + поступово, коли вони стають потрібними вашому постачальнику. - Спільні збирачі допоміжних засобів тепер покривають найпоширеніші сімейства replay/tool-compat, - тому плагінам зазвичай не потрібно вручну підключати кожен hook по одному: + Спільні builder-функції helper-ів тепер покривають найпоширеніші сімейства + replay/tool-compat, тому плагінам зазвичай не потрібно вручну підключати кожен hook окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -281,11 +285,11 @@ x-i18n: | Family | Що воно підключає | | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для сумісних з OpenAI transport, включно з очищенням id викликів інструментів, виправленнями порядку assistant-first і загальною перевіркою ходів Gemini там, де це потрібно transport | - | `anthropic-by-model` | Політика replay з урахуванням Claude, вибрана за `modelId`, тому transport Anthropic-message отримують очищення thinking-блоків, специфічне для Claude, лише коли визначена модель справді має id Claude | - | `google-gemini` | Нативна політика replay Gemini плюс очищення bootstrap replay і режим виводу reasoning з тегами | - | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі transport; не вмикає нативну перевірку replay Gemini або переписування bootstrap | - | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов'язкове відкидання thinking-блоків лише для Claude залишається обмеженим стороною Anthropic | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, зокрема очищення tool-call-id, виправлення порядку assistant-first і загальна валідація Gemini-turn там, де цього потребує транспорт | + | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тому транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді є ідентифікатором Claude | + | `google-gemini` | Власна політика replay Gemini плюс очищення bootstrap replay і режим tagged reasoning-output | + | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає власну валідацію replay Gemini або переписування bootstrap | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове видалення thinking-block лише для Claude залишається обмеженим стороною Anthropic | Реальні вбудовані приклади: @@ -300,12 +304,12 @@ x-i18n: | Family | Що воно підключає | | --- | --- | | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху stream | - | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху proxy stream, де для `kilo/auto` і id proxy reasoning, що не підтримуються, ін'єкція thinking пропускається | - | `moonshot-thinking` | Відображення payload нативного двійкового thinking Moonshot з конфігурації + рівня `/think` | + | `kilocode-thinking` | Обгортка міркування Kilo на спільному шляху проксі-stream, де `kilo/auto` та непідтримувані ідентифікатори міркування проксі пропускають інжектований thinking | + | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot із config + рівня `/think` | | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху stream | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, verbosity тексту, нативний вебпошук Codex, формування payload сумісності reasoning і керування контекстом Responses | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, де пропуски для моделей, що не підтримуються, і `auto` централізовано обробляються | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена типово, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнули явно | + | `openai-responses-defaults` | Спільні власні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, verbosity тексту, власний web search Codex, формування payload для сумісності reasoning і керування контекстом Responses | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, з централізованою обробкою пропусків для непідтримуваних моделей і `auto` | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для таких постачальників, як Z.AI, які хочуть потокову передачу інструментів, якщо її явно не вимкнено | Реальні вбудовані приклади: @@ -318,80 +322,79 @@ x-i18n: - `zai`: `tool-stream-default-on` `openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств replay - разом зі спільними допоміжними засобами, з яких ці сімейства побудовані. Типові публічні експорти + разом зі спільними helper-функціями, на основі яких побудовано ці сімейства. Поширені публічні експорти включають: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - спільні збирачі replay, такі як `buildOpenAICompatibleReplayPolicy(...)`, + - спільні builder-функції replay, як-от `buildOpenAICompatibleReplayPolicy(...)`, `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` і `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - допоміжні засоби replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` + - helper-функції replay Gemini, як-от `sanitizeGoogleGeminiReplayHistory(...)` і `resolveTaggedReasoningOutputMode()` - - допоміжні засоби для endpoint/моделей, такі як `resolveProviderEndpoint(...)`, + - helper-функції для endpoint/моделей, як-от `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` надає і збирач сімейств, і - публічні допоміжні засоби обгорток, які ці сімейства повторно використовують. Типові публічні експорти + `openclaw/plugin-sdk/provider-stream` надає як builder сімейств, + так і публічні helper-обгортки, які ці сімейства повторно використовують. Поширені публічні експорти включають: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - спільні обгортки OpenAI/Codex, такі як + - спільні обгортки OpenAI/Codex, як-от `createOpenAIAttributionHeadersWrapper(...)`, `createOpenAIFastModeWrapper(...)`, `createOpenAIServiceTierWrapper(...)`, `createOpenAIResponsesContextManagementWrapper(...)` і `createCodexNativeWebSearchWrapper(...)` - - спільні proxy/provider-обгортки, такі як `createOpenRouterWrapper(...)`, + - спільні обгортки проксі/постачальників, як-от `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` і `createMinimaxFastModeWrapper(...)` - Деякі stream-допоміжні засоби навмисно залишаються локальними для постачальника. Поточний вбудований + Деякі helper-функції для stream навмисно залишаються локальними для конкретного постачальника. Поточний вбудований приклад: `@openclaw/anthropic-provider` експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і - низькорівневі збирачі обгорток Anthropic зі свого публічного шва `api.ts` / - `contract-api.ts`. Ці допоміжні засоби залишаються специфічними для Anthropic, оскільки - вони також кодують обробку бета-можливостей Claude OAuth і gating `context1m`. + builder-функції нижчого рівня для обгорток Anthropic зі свого публічного інтерфейсу `api.ts` / + `contract-api.ts`. Ці helper-функції залишаються специфічними для Anthropic, оскільки + вони також кодують обробку бета-версій Claude OAuth і обмеження `context1m`. - Інші вбудовані постачальники також зберігають transport-специфічні обгортки локальними, коли - цю поведінку не вдається чисто розділити між сімействами. Поточний приклад: вбудований - плагін xAI зберігає нативне формування xAI Responses у власному - `wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, типовим `tool_stream`, - очищенням strict-tool, що не підтримується, і видаленням - payload reasoning, специфічного для xAI. + Інші вбудовані постачальники також залишають локальними обгортки, специфічні для транспорту, коли + цю поведінку неможливо чисто розділити між сімействами. Поточний приклад: вбудований + плагін xAI залишає власне формування Responses xAI у своєму + `wrapStreamFn`, зокрема переписування alias `/fast`, `tool_stream` за замовчуванням, + очищення непідтримуваних strict-tool і видалення payload reasoning, специфічного для xAI. `openclaw/plugin-sdk/provider-tools` наразі надає одне спільне - сімейство схем інструментів разом зі спільними допоміжними засобами схем/сумісності: + сімейство tool-schema плюс спільні helper-функції schema/compat: - `ProviderToolCompatFamily` документує поточний перелік спільних сімейств. - - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini - + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів. + - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення schema + Gemini + діагностику для постачальників, яким потрібні Gemini-safe tool schemas. - `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)` - — це базові публічні допоміжні засоби для схем Gemini. - - `resolveXaiModelCompatPatch()` повертає вбудований патч сумісності xAI: - `toolSchemaProfile: "xai"`, ключові слова схем, що не підтримуються, нативну - підтримку `web_search` і декодування аргументів викликів інструментів з HTML-сутностей. - - `applyXaiModelCompat(model)` застосовує той самий патч сумісності xAI до - визначеної моделі перед тим, як вона потрапить до раннера. + — це базові публічні helper-функції schema Gemini. + - `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI: + `toolSchemaProfile: "xai"`, непідтримувані ключові слова schema, власну + підтримку `web_search` і декодування аргументів виклику інструментів з HTML-entity. + - `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до + визначеної моделі, перш ніж вона потрапить до runner. Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс - `contributeResolvedModelCompat`, щоб ці метадані сумісності залишалися у володінні - постачальника, а не жорстко кодувалися в core як правила xAI. + `contributeResolvedModelCompat`, щоб зберегти ці метадані compat у власності + постачальника, а не жорстко кодувати правила xAI в core. - Той самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників: + Такий самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників: - - `@openclaw/openai-provider`: `api.ts` експортує збирачі постачальника, - допоміжні засоби типових моделей і збирачі постачальника realtime - - `@openclaw/openrouter-provider`: `api.ts` експортує збирач постачальника - плюс допоміжні засоби для онбордингу/конфігурації + - `@openclaw/openai-provider`: `api.ts` експортує builder-функції постачальника, + helper-функції для моделей за замовчуванням і builder-функції постачальника realtime + - `@openclaw/openrouter-provider`: `api.ts` експортує builder-функцію постачальника + плюс helper-функції для onboarding/config - - Для постачальників, яким потрібен обмін токенів перед кожним викликом inference: + + Для постачальників, яким потрібен обмін токенами перед кожним викликом inference: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -404,8 +407,8 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту: + + Для постачальників, яким потрібні користувацькі заголовки запиту або зміни тіла запиту: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -422,9 +425,9 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні нативні заголовки або метадані - запиту/сеансу в загальних transport HTTP або WebSocket: + + Для постачальників, яким потрібні власні заголовки запиту/сесії або метадані на + універсальних HTTP- чи WebSocket-транспортах: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -444,8 +447,8 @@ x-i18n: }), ``` - - Для постачальників, які надають дані usage/білінгу: + + Для постачальників, які надають дані про використання/білінг: ```typescript resolveUsageAuth: async (ctx) => { @@ -464,79 +467,79 @@ x-i18n: | # | Hook | Коли використовувати | | --- | --- | --- | - | 1 | `catalog` | Каталог моделей або типові значення base URL | - | 2 | `applyConfigDefaults` | Глобальні типові значення, якими володіє постачальник, під час materialization конфігурації | - | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів model-id перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | - | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування compat нативного streaming-usage для конфігурованих постачальників | - | 7 | `resolveConfigApiKey` | Визначення автентифікації через env-marker, яким володіє постачальник | - | 8 | `resolveSyntheticAuth` | Synthetic auth для local/self-hosted або на основі конфігурації | - | 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет synthetic placeholder збереженого профілю порівняно з env/config auth | - | 10 | `resolveDynamicModel` | Приймати довільні id моделей вище за потоком | + | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | + | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization config | + | 3 | `normalizeModelId` | Очищення aliases застарілих/preview model-id перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним збиранням моделі | + | 5 | `normalizeConfig` | Нормалізація config `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Переписування compat для власного streaming-usage для постачальників config | + | 7 | `resolveConfigApiKey` | Визначення автентифікації за env-marker, що належить постачальнику | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація local/self-hosted або на основі config | + | 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет синтетичних placeholders збереженого профілю відносно env/config auth | + | 10 | `resolveDynamicModel` | Прийом довільних upstream model IDs | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | - | 12 | `normalizeResolvedModel` | Переписування transport перед раннером | + | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | - Примітки щодо runtime fallback: + Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші - плагіни постачальників із підтримкою hook, доки один із них справді не змінить конфігурацію. - Якщо жоден hook постачальника не перепише підтримуваний запис конфігурації сімейства Google, - вбудований нормалізатор конфігурації Google усе одно застосовується. - - `resolveConfigApiKey` використовує hook постачальника, якщо той наданий. Вбудований - шлях `amazon-bedrock` також має тут вбудований AWS env-marker resolver, - хоча сама runtime-автентифікація Bedrock і далі використовує стандартний + - `normalizeConfig` спочатку перевіряє відповідного постачальника, потім інші + плагіни постачальників, здатні обробляти hooks, доки один із них справді не змінить config. + Якщо жоден hook постачальника не перепише підтримуваний запис config сімейства Google, + усе одно застосовується вбудований нормалізатор config Google. + - `resolveConfigApiKey` використовує hook постачальника, якщо він доступний. Вбудований + шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, + хоча сама runtime auth Bedrock усе ще використовує стандартний ланцюжок AWS SDK. - | 13 | `contributeResolvedModelCompat` | Прапорці compat для моделей постачальника за іншим сумісним transport | + | 13 | `contributeResolvedModelCompat` | Прапори compat для моделей вендора за іншим сумісним транспортом | | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення схем інструментів, яким володіє постачальник, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика схем інструментів, якою володіє постачальник | - | 17 | `resolveReasoningOutputMode` | Контракт виводу reasoning з тегами чи нативний | - | 18 | `prepareExtraParams` | Типові параметри запиту | - | 19 | `createStreamFn` | Повністю власний transport StreamFn | - | 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла на звичайному шляху stream | - | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного ходу | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сеансу WS/cool-down | - | 23 | `formatApiKey` | Власна форма runtime-токена | - | 24 | `refreshOAuth` | Власне оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Підказка щодо відновлення автентифікації | - | 26 | `matchesContextOverflowError` | Виявлення переповнення, яким володіє постачальник | - | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, якою володіє постачальник | + | 15 | `normalizeToolSchemas` | Очищення tool-schema, що належить постачальнику, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика tool-schema, що належить постачальнику | + | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output | + | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | + | 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn | + | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному шляху stream | + | 21 | `resolveTransportTurnState` | Власні заголовки/метадані для кожного turn | + | 22 | `resolveWebSocketSessionPolicy` | Власні заголовки сесії WS / період охолодження | + | 23 | `formatApiKey` | Користувацька форма runtime token | + | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | + | 25 | `buildAuthDoctorHint` | Підказка щодо виправлення автентифікації | + | 26 | `matchesContextOverflowError` | Визначення переповнення, що належить постачальнику | + | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | | 28 | `isCacheTtlEligible` | Керування TTL кешу prompt | - | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховати застарілі рядки вище за потоком | - | 31 | `augmentModelCatalog` | Synthetic рядки сумісності вперед у каталозі | - | 32 | `isBinaryThinking` | Двійкове thinking увімк./вимк. | + | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Приховати застарілі upstream rows | + | 31 | `augmentModelCatalog` | Синтетичні rows для forward-compat | + | 32 | `isBinaryThinking` | Бінарний thinking увімк./вимк. | | 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` | - | 34 | `resolveDefaultThinkingLevel` | Типова політика `/think` | - | 35 | `isModernModelRef` | Зіставлення live/smoke моделей | - | 36 | `prepareRuntimeAuth` | Обмін токенів перед inference | - | 37 | `resolveUsageAuth` | Власний парсинг облікових даних usage | - | 38 | `fetchUsageSnapshot` | Власний endpoint usage | - | 39 | `createEmbeddingProvider` | Адаптер embedding для memory/search, яким володіє постачальник | - | 40 | `buildReplayPolicy` | Власна політика replay/compaction transcript | + | 34 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням | + | 35 | `isModernModelRef` | Відповідність live/smoke моделей | + | 36 | `prepareRuntimeAuth` | Обмін токенами перед inference | + | 37 | `resolveUsageAuth` | Користувацький розбір облікових даних usage | + | 38 | `fetchUsageSnapshot` | Користувацький endpoint usage | + | 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для memory/search | + | 40 | `buildReplayPolicy` | Користувацька політика replay/compaction транскрипту | | 41 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | - | 42 | `validateReplayTurns` | Сувора перевірка ходів replay перед вбудованим раннером | - | 43 | `onModelSelected` | Зворотний виклик після вибору (наприклад, телеметрія) | + | 42 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner | + | 43 | `onModelSelected` | Колбек після вибору моделі (наприклад, telemetry) | Примітка щодо налаштування prompt: - - `resolveSystemPromptContribution` дає постачальнику змогу додавати - системні підказки з урахуванням кешу для сімейства моделей. Віддавайте цьому перевагу замість - `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделей + - `resolveSystemPromptContribution` дозволяє постачальнику додавати cache-aware + інструкції до system prompt для сімейства моделей. Віддавайте йому перевагу перед + `before_prompt_build`, якщо поведінка належить одному сімейству постачальника/моделей і має зберігати стабільний/динамічний поділ кешу. - Детальні описи й приклади з реального світу дивіться в + Докладні описи та реальні приклади дивіться в [Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks). - + Плагін постачальника може реєструвати speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch - і web search разом із текстовим inference: + і web search поряд із текстовим inference: ```typescript register(api) { @@ -645,23 +648,23 @@ x-i18n: ``` OpenClaw класифікує це як плагін **hybrid-capability**. Це - рекомендований шаблон для корпоративних плагінів (один плагін на постачальника). Дивіться + рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див. [Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model). - Для генерації відео віддавайте перевагу показаній вище структурі можливостей із урахуванням режимів: - `generate`, `imageToVideo` і `videoToVideo`. Плоскі агреговані поля на - кшталт `maxInputImages`, `maxInputVideos` і `maxDurationSeconds` - недостатні, щоб чисто оголошувати підтримку режимів перетворення або вимкнених режимів. + Для генерації відео віддавайте перевагу наведеній вище структурі можливостей з урахуванням режимів: + `generate`, `imageToVideo` і `videoToVideo`. Пласкі агреговані поля, такі + як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, недостатні, + щоб коректно оголошувати підтримку режимів трансформації або вимкнені режими. Постачальники генерації музики мають дотримуватися того самого шаблону: `generate` для генерації лише за prompt і `edit` для генерації - на основі еталонного зображення. Плоскі агреговані поля на кшталт `maxInputImages`, - `supportsLyrics` і `supportsFormat` недостатні для оголошення підтримки редагування; + на основі референсного зображення. Пласкі агреговані поля, такі як `maxInputImages`, + `supportsLyrics` і `supportsFormat`, недостатні, щоб оголосити підтримку edit; очікуваним контрактом є явні блоки `generate` / `edit`. - + ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; @@ -696,45 +699,45 @@ x-i18n: -## Опублікуйте в ClawHub +## Публікація в ClawHub -Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін: +Плагіни постачальників публікуються так само, як і будь-які інші зовнішні кодові плагіни: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів мають використовувати +Не використовуйте тут застарілий alias публікації лише для Skills; пакети плагінів мають використовувати `clawhub package publish`. ## Структура файлів ``` /acme-ai/ -├── package.json # metadata openclaw.providers -├── openclaw.plugin.json # Маніфест із providerAuthEnvVars +├── package.json # openclaw.providers metadata +├── openclaw.plugin.json # Manifest with provider auth metadata ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Тести - └── usage.ts # Endpoint usage (необов'язково) + ├── provider.test.ts # Tests + └── usage.ts # Usage endpoint (optional) ``` -## Довідник щодо порядку каталогів +## Довідка щодо порядку catalog -`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих +`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих постачальників: -| Порядок | Коли | Випадок використання | -| --------- | ------------- | ----------------------------------------------- | -| `simple` | Перший прохід | Звичайні постачальники з API-ключем | -| `profile` | Після simple | Постачальники, обмежені профілями автентифікації | -| `paired` | Після profile | Синтезувати кілька пов'язаних записів | -| `late` | Останній прохід | Перевизначити наявних постачальників (виграє при колізії) | +| Order | Коли | Випадок використання | +| --------- | ------------- | --------------------------------------------- | +| `simple` | Перший прохід | Звичайні постачальники з API key | +| `profile` | Після simple | Постачальники, прив’язані до профілів auth | +| `paired` | Після profile | Синтез кількох пов’язаних записів | +| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) | ## Наступні кроки - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал -- [SDK Runtime](/uk/plugins/sdk-runtime) — допоміжні засоби `api.runtime` (TTS, пошук, subagent) -- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник імпортів subpath -- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — подробиці про hooks і вбудовані приклади +- [SDK Runtime](/uk/plugins/sdk-runtime) — helper-функції `api.runtime` (TTS, search, subagent) +- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпорту subpath +- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — деталі hooks і приклади вбудованих реалізацій