diff --git a/docs/uk/concepts/context-engine.md b/docs/uk/concepts/context-engine.md index 8da3b8be5..633555e64 100644 --- a/docs/uk/concepts/context-engine.md +++ b/docs/uk/concepts/context-engine.md @@ -1,15 +1,15 @@ --- read_when: - Ви хочете зрозуміти, як OpenClaw збирає контекст моделі - - Ви перемикаєтеся між застарілим механізмом і механізмом плагіна + - Ви перемикаєтеся між застарілим механізмом і механізмом на основі плагіна - Ви створюєте плагін механізму контексту -summary: 'Механізм контексту: розширюване збирання контексту, compaction і життєвий цикл subagent' +summary: 'Механізм контексту: підключуване збирання контексту, компактування та життєвий цикл субагентів' title: Механізм контексту x-i18n: - generated_at: "2026-04-05T18:00:54Z" + generated_at: "2026-04-07T08:01:17Z" model: gpt-5.4 provider: openai - source_hash: 19fd8cbb0e953f58fd84637fc4ceefc65984312cf2896d338318bc8cf860e6d9 + source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1 source_path: concepts/context-engine.md workflow: 15 --- @@ -17,8 +17,8 @@ x-i18n: # Механізм контексту **Механізм контексту** керує тим, як OpenClaw будує контекст моделі для кожного запуску. -Він визначає, які повідомлення включати, як підсумовувати старішу історію та -як керувати контекстом через межі subagent. +Він вирішує, які повідомлення включати, як підсумовувати давнішу історію та +як керувати контекстом через межі субагентів. OpenClaw постачається з вбудованим механізмом `legacy`. Плагіни можуть реєструвати альтернативні механізми, які замінюють активний життєвий цикл механізму контексту. @@ -35,8 +35,8 @@ cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine' ### Встановлення плагіна механізму контексту -Плагіни механізму контексту встановлюються так само, як і будь-який інший плагін OpenClaw. Спочатку встановіть плагін, -а потім виберіть механізм у slot: +Плагіни механізму контексту встановлюються так само, як і будь-які інші плагіни OpenClaw. Спочатку встановіть +його, а потім виберіть механізм у слоті: ```bash # Install from npm @@ -67,38 +67,38 @@ openclaw plugins install -l ./my-context-engine Після встановлення та налаштування перезапустіть gateway. -Щоб повернутися до вбудованого механізму, задайте `contextEngine` значення `"legacy"` (або -повністю видаліть цей ключ — `"legacy"` є типовим значенням). +Щоб повернутися до вбудованого механізму, встановіть `contextEngine` у `"legacy"` (або +повністю видаліть цей ключ — `"legacy"` використовується за замовчуванням). ## Як це працює -Щоразу, коли OpenClaw запускає промпт моделі, механізм контексту бере участь +Щоразу, коли OpenClaw запускає запит моделі, механізм контексту бере участь у чотирьох точках життєвого циклу: -1. **Ingest** — викликається, коли нове повідомлення додається до сесії. Механізм +1. **Ingest** — викликається, коли до сесії додається нове повідомлення. Механізм може зберегти або проіндексувати повідомлення у власному сховищі даних. 2. **Assemble** — викликається перед кожним запуском моделі. Механізм повертає впорядкований - набір повідомлень (і необов’язковий `systemPromptAddition`), який уміщується - в бюджет токенів. + набір повідомлень (і необов’язковий `systemPromptAddition`), які вміщаються в + бюджет токенів. 3. **Compact** — викликається, коли вікно контексту заповнене або коли користувач запускає - `/compact`. Механізм підсумовує старішу історію, щоб звільнити місце. -4. **After turn** — викликається після завершення запуску. Механізм може зберігати стан, - запускати фоновий compaction або оновлювати індекси. + `/compact`. Механізм підсумовує давнішу історію, щоб звільнити місце. +4. **After turn** — викликається після завершення запуску. Механізм може зберегти стан, + запустити фонове компактування або оновити індекси. -### Життєвий цикл subagent (необов’язково) +### Життєвий цикл субагента (необов’язково) -Наразі OpenClaw викликає один хук життєвого циклу subagent: +Наразі OpenClaw викликає один хук життєвого циклу субагента: -- **onSubagentEnded** — очищення після завершення або прибирання сесії subagent. +- **onSubagentEnded** — очищення після завершення сесії субагента або її прибирання. Хук `prepareSubagentSpawn` є частиною інтерфейсу для майбутнього використання, але -runtime його ще не викликає. +середовище виконання поки що його не викликає. -### Доповнення до системного промпта +### Додавання до системного промпту Метод `assemble` може повертати рядок `systemPromptAddition`. OpenClaw -додає його на початок системного промпта для запуску. Це дає механізмам змогу вставляти -динамічні вказівки для пригадування, інструкції з retrieval або підказки з урахуванням контексту +додає його на початок системного промпту для запуску. Це дозволяє механізмам додавати +динамічні вказівки для пригадування, інструкції для retrieval або підказки з урахуванням контексту без потреби у статичних файлах робочого простору. ## Механізм legacy @@ -106,22 +106,24 @@ runtime його ще не викликає. Вбудований механізм `legacy` зберігає початкову поведінку OpenClaw: - **Ingest**: no-op (менеджер сесій безпосередньо обробляє збереження повідомлень). -- **Assemble**: наскрізний прохід (наявний конвеєр sanitize → validate → limit - у runtime обробляє збирання контексту). -- **Compact**: делегує вбудованому compaction із підсумовуванням, який створює - єдиний підсумок старіших повідомлень і зберігає недавні повідомлення без змін. +- **Assemble**: pass-through (наявний конвеєр sanitize → validate → limit + у середовищі виконання обробляє збирання контексту). +- **Compact**: делегує вбудованому компактуванню з підсумовуванням, яке створює + єдине резюме старіших повідомлень і зберігає недоторканими недавні повідомлення. - **After turn**: no-op. Механізм legacy не реєструє інструменти й не надає `systemPromptAddition`. -Коли `plugins.slots.contextEngine` не задано (або має значення `"legacy"`), цей +Коли `plugins.slots.contextEngine` не встановлено (або встановлено в `"legacy"`), цей механізм використовується автоматично. -## Механізми плагінів +## Механізми на основі плагінів -Плагін може зареєструвати механізм контексту через API плагінів: +Плагін може зареєструвати механізм контексту за допомогою API плагінів: ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function register(api) { api.registerContextEngine("my-engine", () => ({ info: { @@ -135,12 +137,15 @@ export default function register(api) { return { ingested: true }; }, - async assemble({ sessionId, messages, tokenBudget }) { + async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) { // Return messages that fit the budget return { messages: buildContext(messages, tokenBudget), estimatedTokens: countTokens(messages), - systemPromptAddition: "Use lcm_grep to search history...", + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), }; }, @@ -175,59 +180,59 @@ export default function register(api) { | Елемент | Тип | Призначення | | ------------------ | -------- | -------------------------------------------------------- | -| `info` | Властивість | Ідентифікатор, назва, версія механізму та ознака володіння compaction | +| `info` | Властивість | Ідентифікатор механізму, назва, версія та чи керує він компактуванням | | `ingest(params)` | Метод | Зберегти одне повідомлення | | `assemble(params)` | Метод | Побудувати контекст для запуску моделі (повертає `AssembleResult`) | -| `compact(params)` | Метод | Підсумувати/зменшити контекст | +| `compact(params)` | Метод | Підсумувати/скоротити контекст | `assemble` повертає `AssembleResult` з такими полями: -- `messages` — впорядковані повідомлення, які надсилаються моделі. -- `estimatedTokens` (обов’язково, `number`) — оцінка механізму для загальної - кількості токенів у зібраному контексті. OpenClaw використовує це для рішень - про поріг compaction і для діагностичної звітності. -- `systemPromptAddition` (необов’язково, `string`) — додається на початок системного промпта. +- `messages` — упорядковані повідомлення для надсилання моделі. +- `estimatedTokens` (обов’язкове, `number`) — оцінка механізмом загальної кількості + токенів у зібраному контексті. OpenClaw використовує це для рішень щодо порогу компактування + та діагностичної звітності. +- `systemPromptAddition` (необов’язкове, `string`) — додається на початок системного промпту. Необов’язкові елементи: -| Елемент | Тип | Призначення | -| ----------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- | +| Елемент | Тип | Призначення | +| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- | | `bootstrap(params)` | Метод | Ініціалізувати стан механізму для сесії. Викликається один раз, коли механізм уперше бачить сесію (наприклад, імпорт історії). | -| `ingestBatch(params)` | Метод | Обробити завершений хід як пакет. Викликається після завершення запуску, одразу з усіма повідомленнями цього ходу. | -| `afterTurn(params)` | Метод | Робота життєвого циклу після запуску (збереження стану, запуск фонового compaction). | -| `prepareSubagentSpawn(params)`| Метод | Налаштувати спільний стан для дочірньої сесії. | -| `onSubagentEnded(params)` | Метод | Очистити стан після завершення subagent. | -| `dispose()` | Метод | Звільнити ресурси. Викликається під час завершення роботи gateway або перезавантаження плагіна — не для кожної сесії. | +| `ingestBatch(params)` | Метод | Прийняти завершений хід пакетом. Викликається після завершення запуску з усіма повідомленнями цього ходу одразу. | +| `afterTurn(params)` | Метод | Робота життєвого циклу після запуску (збереження стану, запуск фонового компактування). | +| `prepareSubagentSpawn(params)`| Метод | Налаштувати спільний стан для дочірньої сесії. | +| `onSubagentEnded(params)` | Метод | Очистити ресурси після завершення субагента. | +| `dispose()` | Метод | Звільнити ресурси. Викликається під час вимкнення gateway або перезавантаження плагіна — не для кожної сесії. | ### ownsCompaction -`ownsCompaction` визначає, чи залишатиметься ввімкненим вбудований auto-compaction Pi у межах спроби -для цього запуску: +`ownsCompaction` визначає, чи залишається вбудоване автоматичне компактування Pi під час спроби +увімкненим для запуску: -- `true` — механізм сам керує поведінкою compaction. OpenClaw вимикає вбудований - auto-compaction Pi для цього запуску, а реалізація `compact()` у механізмі - відповідає за `/compact`, compaction для відновлення після переповнення та будь-який проактивний - compaction, який механізм хоче виконувати в `afterTurn()`. -- `false` або не задано — вбудований auto-compaction Pi усе ще може виконуватися під час - виконання промпта, але метод `compact()` активного механізму все одно викликається для +- `true` — механізм керує поведінкою компактування. OpenClaw вимикає вбудоване в Pi + автоматичне компактування для цього запуску, а реалізація `compact()` механізму + відповідає за `/compact`, компактування для відновлення після переповнення та будь-яке проактивне + компактування, яке він хоче виконувати в `afterTurn()`. +- `false` або не встановлено — вбудоване автоматичне компактування Pi все ще може виконуватися під час + виконання промпту, але метод `compact()` активного механізму все одно викликається для `/compact` і відновлення після переповнення. -`ownsCompaction: false` **не** означає, що OpenClaw автоматично повертається до -шляху compaction механізму legacy. +`ownsCompaction: false` **не** означає, що OpenClaw автоматично повертається +до шляху компактування механізму legacy. -Це означає, що існують два коректні шаблони для плагінів: +Це означає, що існують два коректні шаблони плагінів: -- **Режим володіння** — реалізуйте власний алгоритм compaction і задайте +- **Режим керування** — реалізуйте власний алгоритм компактування й встановіть `ownsCompaction: true`. -- **Режим делегування** — задайте `ownsCompaction: false` і нехай `compact()` викликає +- **Режим делегування** — встановіть `ownsCompaction: false` і зробіть так, щоб `compact()` викликав `delegateCompactionToRuntime(...)` з `openclaw/plugin-sdk/core`, щоб використовувати - вбудовану поведінку compaction OpenClaw. + вбудовану поведінку компактування OpenClaw. -No-op `compact()` небезпечний для активного механізму без власного керування, оскільки -він вимикає звичайний шлях `/compact` і compaction для відновлення після переповнення для -цього slot механізму. +No-op `compact()` є небезпечним для активного некеруючого механізму, оскільки він +вимикає звичайний шлях компактування `/compact` і відновлення після переповнення для цього +слота механізму. -## Довідник конфігурації +## Довідка з конфігурації ```json5 { @@ -241,41 +246,47 @@ No-op `compact()` небезпечний для активного механі } ``` -Slot є взаємовиключним під час виконання — лише один зареєстрований механізм контексту -визначається для певного запуску або операції compaction. Інші увімкнені -плагіни `kind: "context-engine"` усе ще можуть завантажуватися і виконувати свій код -реєстрації; `plugins.slots.contextEngine` лише вибирає, який зареєстрований id механізму -OpenClaw має визначити, коли йому потрібен механізм контексту. +Слот є ексклюзивним під час виконання — лише один зареєстрований механізм контексту +визначається для певного запуску або операції компактування. Інші увімкнені +плагіни `kind: "context-engine"` все одно можуть завантажуватися й виконувати свій код +реєстрації; `plugins.slots.contextEngine` лише вибирає, який зареєстрований ідентифікатор механізму +OpenClaw визначає, коли йому потрібен механізм контексту. -## Зв’язок із compaction і пам’яттю +## Зв’язок із компактуванням і пам’яттю - **Compaction** — це одна з відповідальностей механізму контексту. Механізм legacy - делегує до вбудованого підсумовування OpenClaw. Механізми плагінів можуть реалізовувати - будь-яку стратегію compaction (підсумки DAG, vector retrieval тощо). + делегує вбудованому підсумовуванню OpenClaw. Механізми на основі плагінів можуть реалізовувати + будь-яку стратегію компактування (DAG-резюме, vector retrieval тощо). - **Плагіни пам’яті** (`plugins.slots.memory`) відокремлені від механізмів контексту. - Плагіни пам’яті надають пошук/retrieval; механізми контексту керують тим, що + Плагіни пам’яті забезпечують пошук/retrieval; механізми контексту контролюють, що бачить модель. Вони можуть працювати разом — механізм контексту може використовувати дані - плагіна пам’яті під час assemble. -- **Обрізання сесії** (trim старих результатів інструментів у пам’яті) усе ще виконується + плагіна пам’яті під час збирання. Механізмам на основі плагінів, яким потрібен активний шлях + промпту пам’яті, слід віддавати перевагу `buildMemorySystemPromptAddition(...)` з + `openclaw/plugin-sdk/core`, який перетворює активні секції промпту пам’яті + на готовий до додавання на початок `systemPromptAddition`. Якщо механізму потрібен контроль + нижчого рівня, він усе одно може отримувати сирі рядки з + `openclaw/plugin-sdk/memory-host-core` через + `buildActiveMemoryPromptSection(...)`. +- **Обрізання сесії** (скорочення старих результатів інструментів у пам’яті) усе ще виконується незалежно від того, який механізм контексту активний. ## Поради -- Використовуйте `openclaw doctor`, щоб перевірити, що ваш механізм завантажується правильно. -- Якщо ви перемикаєте механізми, наявні сесії продовжують роботу зі своєю поточною історією. - Новий механізм перебирає керування для майбутніх запусків. +- Використовуйте `openclaw doctor`, щоб перевірити, чи ваш механізм завантажується правильно. +- Якщо ви перемикаєте механізми, наявні сесії продовжують працювати з поточною історією. + Новий механізм перебирає роботу на себе для майбутніх запусків. - Помилки механізму журналюються й відображаються в діагностиці. Якщо механізм плагіна - не вдається зареєструвати або вибраний id механізму не вдається визначити, OpenClaw - не виконує автоматичне резервне повернення; запуски завершуються помилкою, доки ви не виправите плагін або + не вдається зареєструвати або не вдається визначити вибраний ідентифікатор механізму, OpenClaw + не виконує автоматичний перехід; запуски завершуються з помилкою, доки ви не виправите плагін або не перемкнете `plugins.slots.contextEngine` назад на `"legacy"`. -- Для розробки використовуйте `openclaw plugins install -l ./my-engine`, щоб прив’язати +- Для розробки використовуйте `openclaw plugins install -l ./my-engine`, щоб підключити локальний каталог плагіна без копіювання. -Див. також: [Compaction](/concepts/compaction), [Контекст](/concepts/context), -[Плагіни](/tools/plugin), [Маніфест плагіна](/plugins/manifest). +Див. також: [Компактування](/uk/concepts/compaction), [Контекст](/uk/concepts/context), +[Плагіни](/uk/tools/plugin), [Маніфест плагіна](/uk/plugins/manifest). ## Пов’язане -- [Контекст](/concepts/context) — як будується контекст для ходів агента -- [Архітектура плагінів](/plugins/architecture) — реєстрація плагінів механізму контексту -- [Compaction](/concepts/compaction) — підсумовування довгих розмов +- [Контекст](/uk/concepts/context) — як будується контекст для ходів агента +- [Архітектура плагінів](/uk/plugins/architecture) — реєстрація плагінів механізму контексту +- [Компактування](/uk/concepts/compaction) — підсумовування довгих розмов diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 55f7e29cc..0f80a1441 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -3,124 +3,124 @@ read_when: - Створення або налагодження нативних плагінів OpenClaw - Розуміння моделі можливостей плагінів або меж володіння - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація runtime-хуків провайдера або плагінів каналів + - Реалізація гачків середовища виконання провайдера або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішня будова плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' -title: Внутрішня будова плагінів +summary: 'Внутрішні компоненти плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' +title: Внутрішні компоненти плагінів x-i18n: - generated_at: "2026-04-07T06:57:43Z" + generated_at: "2026-04-07T08:06:01Z" model: gpt-5.4 provider: openai - source_hash: ba93f0a748e46ac7c7b9d10d78260e6e13b6e533d85a0b56f3c1ffa8ee5a3850 + source_hash: a48b387152c5a6a9782c5aaa9d6c215c16adb7cb256302d3e85f80b03f9b6898 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішня будова плагінів +# Внутрішні компоненти плагінів - Це **детальний довідник з архітектури**. Практичні посібники див. тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача - - [Початок роботи](/uk/plugins/building-plugins) — перший посібник зі створення плагіна + Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувачів + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей - - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації + - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** в OpenClaw. Кожен +Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади плагінів | -| --------------------- | ---------------------------------------------- | ------------------------------------ | -| Текстове виведення | `api.registerProvider(...)` | `openai`, `anthropic` | -| Бекенд виведення CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Можливість | Метод реєстрації | Приклади плагінів | +| --------------------- | ----------------------------------------------- | ------------------------------------ | +| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | +| Бекенд CLI інференсу | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веб-витягування | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або -сервіси, є **застарілим hook-only** плагіном. Цей шаблон усе ще повністю підтримується. +Плагін, який не реєструє жодної можливості, але надає гачки, інструменти або +сервіси, є **застарілим плагіном лише з гачками**. Цей шаблон і далі повністю підтримується. -### Позиція щодо зовнішньої сумісності +### Позиція щодо сумісності із зовнішніми плагінами -Модель можливостей уже впроваджена в core і сьогодні використовується +Модель можливостей уже реалізована в core і сьогодні використовується вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще -потребує суворішої планки, ніж «це експортується, отже це незмінне». +потребує чіткішої планки, ніж «це експортується, отже, це зафіксовано». Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте +- **наявні зовнішні плагіни:** зберігати працездатність інтеграцій на основі гачків; вважати це базовим рівнем сумісності -- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей, а не - vendor-specific reach-in або новим hook-only дизайнам +- **нові вбудовані/нативні плагіни:** надавати перевагу явній реєстрації можливостей замість + vendor-специфічних прямолінійних доступів або нових реалізацій лише з гачками - **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але - вважайте surfaces допоміжних засобів, специфічних для можливостей, такими, що розвиваються, - доки в документації контракт явно не позначено як стабільний + допоміжні поверхні, специфічні для можливостей, слід вважати такими, що розвиваються, + якщо в документації контракт явно не позначено як стабільний Практичне правило: -- API реєстрації можливостей — це запланований напрям -- застарілі хуки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час +- API реєстрації можливостей — це бажаний напрям розвитку +- застарілі гачки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час переходу -- не всі експортовані helper subpath однакові; віддавайте перевагу вузькому задокументованому - контракту, а не випадковим експортам допоміжних засобів +- не всі експортовані підшляхи допоміжних засобів однаково важливі; надавайте перевагу вузькому документованому + контракту, а не випадковим допоміжним експортам ### Форми плагінів OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки реєстрації (а не лише статичних метаданих): +поведінки під час реєстрації (а не лише статичних метаданих): -- **plain-capability** -- реєструє рівно один тип можливостей (наприклад - плагін тільки провайдера, як-от `mistral`) -- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад - `openai` володіє текстовим виведенням, мовленням, розумінням медіа та генерацією - зображень) -- **hook-only** -- реєструє лише хуки (типізовані або custom), без можливостей, - інструментів, команд чи сервісів +- **plain-capability** -- реєструє рівно один тип можливості (наприклад, + плагін лише провайдера, як-от `mistral`) +- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, + `openai` володіє текстовим інференсом, мовленням, розумінням медіа та + генерацією зображень) +- **hook-only** -- реєструє лише гачки (типізовані або користувацькі), без можливостей, + інструментів, команд або сервісів - **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але без можливостей Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та -розбивку можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). +розподіл за можливостями. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). -### Застарілі хуки +### Застарілі гачки -Хук `before_agent_start` залишається підтримуваним шляхом сумісності для -hook-only плагінів. Реальні застарілі плагіни все ще залежать від нього. +Гачок `before_agent_start` і далі підтримується як шлях сумісності для +плагінів лише з гачками. Реальні застарілі плагіни все ще від нього залежать. -Напрям: +Напрям розвитку: - зберігати його працездатність - документувати його як застарілий -- для роботи з перевизначенням моделі/провайдера віддавати перевагу `before_model_resolve` -- для мутації prompt віддавати перевагу `before_prompt_build` -- видаляти лише після того, як реальне використання зменшиться, а покриття fixture підтвердить безпечність міграції +- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve` +- для модифікації промпту надавати перевагу `before_prompt_build` +- вилучати лише після зниження реального використання та підтвердження безпеки міграції покриттям фікстурами ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити -одну з таких міток: +одну з цих позначок: | Сигнал | Значення | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація коректно парситься, а плагіни успішно визначаються | -| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який застарів | -| **hard error** | Конфігурація недійсна або не вдалося завантажити плагін | +| **config valid** | Конфігурація коректно парситься, і плагіни успішно визначаються | +| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | +| **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`. ## Огляд архітектури @@ -128,59 +128,59 @@ hook-only плагінів. Реальні застарілі плагіни в Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить кандидатів на плагіни із налаштованих шляхів, коренів workspace, - глобальних коренів розширень і вбудованих розширень. Виявлення спочатку читає - нативні маніфести `openclaw.plugin.json` і підтримувані маніфести bundle. + OpenClaw знаходить потенційні плагіни в налаштованих шляхах, коренях workspace, + глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json` і маніфести підтримуваних пакетів. 2. **Увімкнення + валідація** - Core вирішує, чи виявлений плагін увімкнений, вимкнений, заблокований або - вибраний для ексклюзивного слота, як-от memory. -3. **Завантаження часу виконання** + Core вирішує, чи знайдений плагін увімкнений, вимкнений, заблокований або + вибраний для ексклюзивного слота, такого як пам’ять. +3. **Завантаження середовища виконання** Нативні плагіни OpenClaw завантажуються в процес через jiti і реєструють - можливості в центральному реєстрі. Сумісні bundle нормалізуються до - записів реєстру без імпорту коду часу виконання. + можливості в центральному реєстрі. Сумісні пакети нормалізуються в + записи реєстру без імпорту коду середовища виконання. 4. **Споживання поверхонь** Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування - провайдерів, хуки, HTTP-маршрути, CLI-команди та сервіси. + провайдерів, гачки, HTTP-маршрути, команди CLI та сервіси. -Спеціально для CLI плагінів виявлення кореневих команд поділено на дві фази: +Зокрема для CLI плагінів, виявлення кореневих команд розділено на дві фази: -- метадані під час парсингу надходять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI плагіна може залишатися lazy і реєструватися під час першого виклику +- метадані на етапі парсингу надходять із `registerCli(..., { descriptors: [...] })` +- справжній модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику -Це дозволяє зберігати CLI-код, що належить плагіну, всередині плагіна, водночас даючи OpenClaw -можливість резервувати імена кореневих команд до парсингу. +Це дозволяє зберігати код CLI, який належить плагіну, всередині плагіна, водночас даючи OpenClaw +можливість резервувати імена кореневих команд до початку парсингу. -Важлива межа дизайну: +Важлива межа проєктування: - виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** без виконання коду плагіна -- нативна поведінка часу виконання походить із шляху `register(api)` модуля плагіна +- нативна поведінка середовища виконання походить із шляху `register(api)` модуля плагіна -Цей поділ дає змогу OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки для UI/схеми до повної активації runtime. +Такий поділ дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +створювати підказки для UI/схеми ще до повної активації середовища виконання. ### Плагіни каналів і спільний інструмент повідомлень Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для -звичайних дій чату. OpenClaw зберігає один спільний інструмент `message` у core, а +звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core, а плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. Поточна межа така: -- core володіє хостом спільного інструмента `message`, wiring prompt, веденням - сесій/гілок та диспетчеризацією виконання -- плагіни каналів володіють виявленням scoped action, виявленням можливостей і будь-якими - фрагментами схеми, специфічними для каналу -- плагіни каналів володіють граматикою розмов сесії, специфічною для провайдера, наприклад - тим, як id розмов кодують id гілок або успадковуються від батьківських розмов -- плагіни каналів виконують фінальну дію через свій action adapter +- core володіє спільним хостом інструмента `message`, підключенням до промптів, веденням + обліку сесій/гілок і диспетчеризацією виконання +- плагіни каналів володіють виявленням дій в області видимості, виявленням можливостей і будь-якими + специфічними для каналу фрагментами схеми +- плагіни каналів володіють граматикою розмов сеансів, специфічною для провайдера, наприклад + тим, як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов +- плагіни каналів виконують фінальну дію через свій адаптер дій -Для плагінів каналів surface SDK — -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик -виявлення дозволяє плагіну повертати видимі дії, можливості та внески до схеми -разом, щоб ці частини не розходилися. +Для плагінів каналів поверхнею SDK є +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення +дозволяє плагіну повернути видимі дії, можливості та внески в схему разом, +щоб ці частини не розходилися. -Core передає runtime scope у цей крок виявлення. Важливі поля: +Core передає область середовища виконання в цей крок виявлення. Важливі поля: - `accountId` - `currentChannelId` @@ -189,126 +189,125 @@ Core передає runtime scope у цей крок виявлення. Важ - `sessionKey` - `sessionId` - `agentId` -- trusted inbound `requesterSenderId` +- довірений вхідний `requesterSenderId` Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або -довіреної ідентичності запитувача без жорстко закодованих гілок, специфічних для каналу, у +довіреної особи відправника запиту без жорсткого кодування специфічних для каналу гілок у core-інструменті `message`. -Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner -відповідає за передавання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб спільний -інструмент `message` показував правильну surface, що належить каналу, для поточного кроку. +Саме тому зміни маршрутизації embedded-runner і далі залишаються роботою плагінів: runner +відповідає за передавання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб +спільний інструмент `message` показував правильну поверхню, що належить каналу, +для поточного ходу. -Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати runtime виконання -всередині власних модулів розширення. Core більше не володіє runtime message-action для Discord, -Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі subpath `plugin-sdk/*-action-runtime`, і вбудовані -плагіни мають імпортувати свій локальний runtime-код безпосередньо з модулів, що -належать їх розширенню. +Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати середовище виконання +виконання всередині власних модулів розширення. Core більше не володіє +середовищами виконання дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані +плагіни мають імпортувати свій локальний код середовища виконання безпосередньо зі своїх +модулів розширення. -Та сама межа застосовується і до provider-named SDK seams загалом: core не повинен -імпортувати зручні channel-specific barrels для Slack, Discord, Signal, -WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, слід або -використати власний barrel `api.ts` / `runtime-api.ts` вбудованого плагіна, або -підняти потребу до вузької узагальненої можливості в спільному SDK. +Та сама межа застосовується і до загальних seams SDK з іменами провайдерів: core не має +імпортувати зручні панелі, специфічні для каналів, для Slack, Discord, Signal, +WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, він має або +використовувати власну панель `api.ts` / `runtime-api.ts` вбудованого плагіна, або підвищити цю потребу +до вузької загальної можливості у спільному SDK. -Спеціально для опитувань є два шляхи виконання: +Зокрема для опитувань є два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, що відповідають загальній +- `outbound.sendPoll` — спільна базова лінія для каналів, які відповідають загальній моделі опитувань -- `actions.handleAction("poll")` — бажаний шлях для channel-specific - семантики опитувань або додаткових параметрів опитувань +- `actions.handleAction("poll")` — бажаний шлях для специфічної для каналу + семантики опитувань або додаткових параметрів опитування -Тепер core відкладає спільний парсинг опитувань до моменту, коли диспетчеризація опитування плагіна -відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати channel-specific -поля опитувань, не блокуючись спершу загальним парсером опитувань. +Тепер core відкладає спільний парсинг опитувань до моменту, коли диспетчеризація опитувань плагіна +відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати специфічні для каналу +поля опитувань, не блокуючись спочатку загальним парсером опитувань. -Повну послідовність запуску див. у [Конвеєрі завантаження](#load-pipeline). +Повну послідовність запуску див. у розділі [Конвеєр завантаження](#load-pipeline). ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір не пов’язаних інтеграцій. +**функції**, а не як набір не пов’язаних між собою інтеграцій. Це означає: - плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, пов’язаними з цією компанією -- плагін функції зазвичай має володіти всією surface функції, яку він вводить -- канали мають споживати спільні можливості core замість ad hoc повторної реалізації - поведінки провайдера +- плагін функції зазвичай має володіти повною поверхнею функції, яку він вводить +- канали мають споживати спільні можливості core замість разового повторного + впровадження поведінки провайдера Приклади: -- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та поведінкою OpenAI - для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та + поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень - вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs - вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft - вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google для розуміння медіа + генерації зображень + веб-пошуку -- вбудований плагін `firecrawl` володіє поведінкою веб-витягування Firecrawl +- вбудований плагін `firecrawl` володіє поведінкою веб-отримання Firecrawl - вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми бекендами розуміння медіа -- плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також - поведінкою для розуміння медіа і генерації відео -- плагін `voice-call` — це плагін функції: він володіє транспортом викликів, інструментами, - CLI, маршрутами та мостом медіапотоку Twilio, але споживає спільні можливості мовлення, +- плагін `voice-call` — це плагін функції: він володіє транспортом дзвінків, інструментами, + CLI, маршрутами та мостом медіапотоків Twilio, але споживає спільні можливості мовлення, а також транскрипції в реальному часі й голосу в реальному часі замість прямого імпорту vendor-плагінів -Бажаний кінцевий стан: +Бажаний кінцевий стан такий: -- OpenAI живе в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та +- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший вендор може зробити те саме для своєї власної surface -- канали не дбають, який vendor-плагін володіє провайдером; вони споживають - спільний контракт можливостей, який надає core +- інший постачальник може так само зробити для власної поверхні +- каналам байдуже, який vendor-плагін володіє провайдером; вони споживають + спільний контракт можливості, який надає core Ось ключова відмінність: - **plugin** = межа володіння - **capability** = контракт core, який можуть реалізовувати або споживати кілька плагінів -Тож якщо OpenClaw додає нову сферу, як-от відео, перше питання — не -«який провайдер має жорстко закодувати обробку відео?» Перше питання — «яким є -контракт core для можливості відео?» Після появи цього контракту vendor-плагіни -зможуть реєструватися для нього, а плагіни каналів/функцій — споживати його. +Отже, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не +«який провайдер має жорстко кодувати обробку відео?». Перше запитання — «який +контракт core для можливості відео?». Коли цей контракт існує, vendor-плагіни +можуть реєструватися для нього, а плагіни каналів/функцій — споживати його. -Якщо можливості ще не існує, правильний крок зазвичай такий: +Якщо можливість ще не існує, правильний крок зазвичай такий: 1. визначити відсутню можливість у core -2. типізовано відкрити її через API/runtime плагінів -3. підключити до цієї можливості канали/функції -4. дозволити vendor-плагінам зареєструвати реалізації +2. типізовано відкрити її через API/середовище виконання плагіна +3. підключити канали/функції до цієї можливості +4. дати vendor-плагінам можливість зареєструвати реалізації -Це зберігає явне володіння й водночас уникає поведінки core, яка залежить від -одного вендора або одноразового коду, специфічного для плагіна. +Це робить володіння явним і водночас уникає поведінки core, що залежить від +одного постачальника або одноразового специфічного для плагіна шляху коду. ### Шарування можливостей -Користуйтеся цією ментальною моделлю, вирішуючи, де має належати код: +Використовуйте цю ментальну модель, вирішуючи, де має знаходитися код: -- **шар можливостей core**: спільна оркестрація, політика, fallback, правила - об’єднання конфігурації, семантика доставки та типізовані контракти -- **шар vendor-плагіна**: vendor-specific API, автентифікація, каталоги моделей, синтез мовлення, - генерація зображень, майбутні відеобекенди, endpoints використання +- **шар можливостей core**: спільна оркестрація, політика, резервний вибір, правила + злиття конфігурації, семантика доставки та типізовані контракти +- **шар vendor-плагіна**: специфічні для постачальника API, автентифікація, каталоги моделей, синтез мовлення, + генерація зображень, майбутні бекенди відео, кінцеві точки використання - **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості core і представляє їх на surface + яка споживає можливості core і надає їх на поверхні Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком fallback, налаштуваннями і доставкою каналом +- core володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями та доставкою в канал - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає helper часу виконання TTS для телефонії +- `voice-call` споживає допоміжний засіб середовища виконання TTS для телефонії -Той самий шаблон слід вважати пріоритетним і для майбутніх можливостей. +Такий самий шаблон слід надавати перевагу й для майбутніх можливостей. -### Приклад плагіна компанії з кількома можливостями +### Приклад компанійного плагіна з кількома можливостями -Плагін компанії має виглядати цілісним зовні. Якщо OpenClaw має спільні +Компанійний плагін має виглядати цілісно ззовні. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веб-витягування і веб-пошуку, -вендор може володіти всіма своїми поверхнями в одному місці: +генерації зображень, генерації відео, веб-отримання та веб-пошуку, +постачальник може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -323,12 +322,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // auth/model catalog/runtime hooks + // гачки auth/каталогу моделей/середовища виконання }); api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — implement the SpeechProviderPlugin interface directly + // конфігурація мовлення постачальника — безпосередньо реалізує інтерфейс SpeechProviderPlugin }); api.registerMediaUnderstandingProvider({ @@ -353,7 +352,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // credential + fetch logic + // логіка облікових даних + отримання }), ); }, @@ -362,84 +361,85 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви helper. Важлива форма: +Важливі не точні назви допоміжних засобів. Важлива форма: -- один плагін володіє surface вендора -- core усе ще володіє контрактами можливостей -- канали та плагіни функцій споживають `api.runtime.*` helpers, а не код вендора -- contract tests можуть стверджувати, що плагін зареєстрував ті можливості, якими - він заявляє, що володіє +- один плагін володіє поверхнею постачальника +- core і далі володіє контрактами можливостей +- канали й плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника +- контрактні тести можуть перевіряти, що плагін зареєстрував ті можливості, + якими, як стверджується, він володіє ### Приклад можливості: розуміння відео OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. Тут застосовується та сама модель володіння: +можливість. До неї застосовується та сама модель володіння: -1. core визначає контракт media-understanding +1. core визначає контракт розуміння медіа 2. vendor-плагіни за потреби реєструють `describeImage`, `transcribeAudio` і `describeVideo` -3. канали та плагіни функцій споживають спільну поведінку core, а не - підключаються напряму до коду вендора +3. канали та плагіни функцій споживають спільну поведінку core замість + прямого підключення до коду постачальника -Це не дає вбудувати припущення про відео від одного провайдера в core. Плагін володіє -surface вендора; core володіє контрактом можливості та поведінкою fallback. +Це дозволяє не вбудовувати припущення одного провайдера щодо відео в core. Плагін володіє +поверхнею постачальника; core володіє контрактом можливості та поведінкою резервного вибору. -Генерація відео вже використовує цю саму послідовність: core володіє типізованим -контрактом можливості та runtime-helper, а vendor-плагіни реєструють +Генерація відео вже використовує ту саму послідовність: core володіє типізованим +контрактом можливості та допоміжним засобом середовища виконання, а vendor-плагіни реєструють реалізації `api.registerVideoGenerationProvider(...)` для нього. -Потрібен конкретний список кроків для впровадження? Див. -[Capability Cookbook](/uk/plugins/architecture). +Потрібен конкретний контрольний список розгортання? Див. +[Практичний посібник із можливостей](/uk/plugins/architecture). -## Контракти та забезпечення +## Контракти та контроль -Поверхня API плагінів навмисно типізована і централізована в +Поверхня API плагінів навмисно типізована та централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -runtime-helpers, на які може покладатися плагін. +допоміжні засоби середовища виконання, на які може покладатися плагін. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт - core може відхиляти дублювання володіння, наприклад коли два плагіни реєструють той самий id провайдера -- під час запуску можна показувати практичні діагностики для некоректної реєстрації -- contract tests можуть забезпечувати володіння вбудованих плагінів і запобігати тихому дрейфу +- під час запуску можна показувати придатну до дії діагностику для некоректної реєстрації +- контрактні тести можуть контролювати володіння вбудованими плагінами та запобігати тихому дрейфу -Є два рівні забезпечення: +Є два шари контролю: -1. **забезпечення під час реєстрації в runtime** +1. **контроль реєстрації під час виконання** Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: - дублікати id провайдерів, дублікати id speech-provider і некоректні + дублікати id провайдерів, дублікати id провайдерів мовлення та некоректні реєстрації створюють діагностику плагіна замість невизначеної поведінки. -2. **contract tests** - Вбудовані плагіни фіксуються в реєстрах контрактів під час тестових запусків, щоб - OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для model - providers, speech providers, web search providers та володіння вбудованою реєстрацією. +2. **контрактні тести** + Вбудовані плагіни фіксуються в контрактних реєстрах під час виконання тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для + провайдерів моделей, провайдерів мовлення, провайдерів веб-пошуку та + володіння вбудованою реєстрацією. Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою -surface володіє. Це дозволяє core і каналам безшовно поєднуватися, оскільки володіння -задеклароване, типізоване і піддається тестуванню, а не є неявним. +поверхнею володіє. Це дозволяє core і каналам безшовно поєднуватися, оскільки +володіння оголошене, типізоване та перевіряється тестами, а не є неявним. -### Що має належати до контракту +### Що має належати контракту Хороші контракти плагінів: - типізовані -- малі +- невеликі - специфічні для можливості - належать core - придатні для повторного використання кількома плагінами -- можуть споживатися каналами/функціями без знань про вендора +- можуть споживатися каналами/функціями без знання про постачальника Погані контракти плагінів: -- vendor-specific політика, прихована в core -- одноразові escape hatch для плагінів, які обходять реєстр -- код каналу, що звертається прямо до реалізації вендора -- ad hoc runtime-об’єкти, які не є частиною `OpenClawPluginApi` або +- політика, специфічна для постачальника, прихована в core +- одноразові обхідні шляхи для плагіна, які оминають реєстр +- код каналу, що напряму звертається до реалізації постачальника +- разові об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а вже потім +Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім дозвольте плагінам підключатися до неї. ## Модель виконання @@ -450,134 +450,134 @@ surface володіє. Це дозволяє core і каналам безшо Наслідки: -- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси -- помилка нативного плагіна може зламати або дестабілізувати gateway -- шкідливий нативний плагін еквівалентний довільному виконанню коду всередині - процесу OpenClaw +- нативний плагін може реєструвати інструменти, мережеві обробники, гачки та сервіси +- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати його +- зловмисний нативний плагін рівнозначний довільному виконанню коду всередині процесу OpenClaw -Сумісні bundle безпечніші за замовчуванням, тому що OpenClaw наразі розглядає їх -як пакети метаданих/контенту. У поточних релізах це здебільшого означає -вбудовані Skills. +Сумісні пакети за замовчуванням безпечніші, оскільки OpenClaw наразі розглядає їх +як пакети метаданих/вмісту. У поточних випусках це переважно означає вбудовані +Skills. -Для не вбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте -workspace-плагіни як код для розробки, а не як виробничі значення за замовчуванням. +Для невбудованих плагінів використовуйте allowlists і явні шляхи встановлення/завантаження. Вважайте +workspace-плагіни кодом часу розробки, а не виробничими значеннями за замовчуванням. -Для назв пакетів вбудованих workspace-плагінів зберігайте id плагіна, прив’язаний до npm-імені: -`@openclaw/` за замовчуванням або схвалений типізований суфікс, як-от -`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли -пакет навмисно відкриває вужчу роль плагіна. +Для імен пакетів у вбудованому workspace id плагіна має бути прив’язаний до npm-імені: +`@openclaw/` за замовчуванням або затверджений типізований суфікс на кшталт +`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, якщо +пакет навмисно надає вужчу роль плагіна. Важливе зауваження щодо довіри: - `plugins.allow` довіряє **id плагінів**, а не походженню джерела. - Workspace-плагін із тим самим id, що й у вбудованого плагіна, навмисно затіняє - вбудовану копію, коли цей workspace-плагін увімкнено/внесено в allowlist. + вбудовану копію, коли такий workspace-плагін увімкнено/додано до allowlist. - Це нормально й корисно для локальної розробки, тестування патчів і hotfix. ## Межа експорту -OpenClaw експортує можливості, а не зручності реалізації. +OpenClaw експортує можливості, а не зручні реалізації. -Зберігайте публічною реєстрацію можливостей. Обрізайте helper-експорти, що не є контрактами: +Зберігайте публічною реєстрацію можливостей. Скорочуйте допоміжні експорти, які не є частиною контракту: -- helper subpath, специфічні для вбудованих плагінів -- runtime plumbing subpath, які не призначені як публічний API -- vendor-specific зручні helpers -- helpers налаштування/onboarding, які є деталями реалізації +- підшляхи допоміжних засобів, специфічні для вбудованих плагінів +- підшляхи внутрішньої логіки середовища виконання, які не призначені як публічний API +- зручні допоміжні засоби, специфічні для постачальника +- допоміжні засоби налаштування/onboarding, що є деталями реалізації -Деякі helper subpath вбудованих плагінів досі залишаються у згенерованій карті -експорту SDK для сумісності та обслуговування вбудованих плагінів. Поточні приклади: +Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються у згенерованій карті експорту SDK +для сумісності та обслуговування вбудованих плагінів. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька seams `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані exports деталей реалізації, а не як рекомендований шаблон SDK для +зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх плагінів. ## Конвеєр завантаження -Під час запуску OpenClaw приблизно робить таке: +Під час запуску OpenClaw приблизно виконує таке: -1. виявляє корені плагінів-кандидатів -2. читає нативні або сумісні bundle-маніфести та метадані пакетів +1. виявляє корені потенційних плагінів +2. читає маніфести нативних або сумісних пакетів і метадані пакетів 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає увімкнення для кожного кандидата +5. визначає стан увімкнення для кожного кандидата 6. завантажує увімкнені нативні модулі через jiti -7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів -8. відкриває реєстр для surfaces команд/runtime +7. викликає нативні гачки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів +8. відкриває реєстр для команд/поверхонь середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, який із них присутній (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. -Запобіжні перевірки відбуваються **до** виконання runtime. Кандидати блокуються, -коли entry виходить за межі кореня плагіна, шлях є world-writable або -володіння шляхом виглядає підозрілим для не вбудованих плагінів. +Перевірки безпеки відбуваються **до** виконання під час runtime. Кандидати блокуються, +якщо точка входу виходить за межі кореня плагіна, шлях має права запису для всіх або +для невбудованих плагінів підозріло виглядає володіння шляхом. ### Поведінка manifest-first -Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: +Маніфест — це джерело істини рівня control-plane. OpenClaw використовує його, щоб: - ідентифікувати плагін -- виявити оголошені канали/skills/схему конфігурації або можливості bundle -- перевірити `plugins.entries..config` -- доповнити мітки/placeholder у Control UI -- показати метадані встановлення/каталогу +- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- перевіряти `plugins.entries..config` +- доповнювати мітки/плейсхолдери Control UI +- показувати метадані встановлення/каталогу -Для нативних плагінів runtime-модуль є частиною data plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. +Для нативних плагінів модуль середовища виконання — це частина data-plane. Він реєструє +фактичну поведінку, таку як гачки, інструменти, команди або потоки провайдера. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі внутрішньопроцесні кеші для: +OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів плагінів +- реєстрів завантажених плагінів -Ці кеші зменшують пікове навантаження під час запуску й накладні витрати від повторних команд. Їх безпечно -розглядати як короткоживучі кеші продуктивності, а не постійне сховище. +Ці кеші зменшують пікове навантаження під час запуску та повторних виконань команд. Їх безпечно +розглядати як короткоживучі кеші продуктивності, а не як постійне сховище. Примітка щодо продуктивності: -- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштовуйте вікна кешування через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені плагіни не змінюють напряму довільні глобальні об’єкти core. Вони реєструються в +Завантажені плагіни не змінюють напряму довільні глобальні змінні core. Вони реєструються в центральному реєстрі плагінів. Реєстр відстежує: -- записи плагінів (ідентичність, джерело, походження, стан, діагностика) +- записи плагінів (ідентичність, джерело, походження, статус, діагностика) - інструменти -- застарілі хуки і типізовані хуки +- застарілі гачки й типізовані гачки - канали -- провайдери -- обробники Gateway RPC +- провайдерів +- обробники gateway RPC - HTTP-маршрути -- CLI-реєстратори +- реєстратори CLI - фонові сервіси -- команди, що належать плагінам +- команди, що належать плагіну -Потім функції core читають із цього реєстру замість прямого звернення до модулів плагінів. -Це підтримує одностороннє завантаження: +Потім можливості core читають із цього реєстру замість прямої взаємодії з модулями плагінів. +Це робить завантаження односпрямованим: - модуль плагіна -> реєстрація в реєстрі -- runtime core -> споживання реєстру +- середовище виконання core -> споживання з реєстру -Це розділення важливе для супроводу. Воно означає, що більшості поверхонь core потрібна -лише одна точка інтеграції: «прочитати реєстр», а не «створити special case для кожного модуля плагіна». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core +потрібна лише одна точка інтеграції: «читати реєстр», а не «окремо обробляти кожен +модуль плагіна». -## Колбеки прив’язки розмов +## Зворотні виклики прив’язки розмови -Плагіни, які прив’язують розмову, можуть реагувати, коли погодження вирішено. +Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку -схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після схвалення або відхилення +запиту на прив’язку: ```ts export default { @@ -585,19 +585,19 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // Тепер існує прив’язка для цього плагіна + розмови. console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // Запит було відхилено; очистіть будь-який локальний стан очікування. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля payload колбека: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` @@ -605,19 +605,19 @@ export default { - `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей колбек є лише сповіщенням. Він не змінює того, хто має право прив’язувати +Цей зворотний виклик призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати розмову, і запускається після завершення обробки схвалення в core. -## Runtime-хуки провайдера +## Гачки середовища виконання провайдера Тепер плагіни провайдерів мають два шари: - метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера до завантаження runtime, `channelEnvVars` для дешевого пошуку env/setup каналу - до завантаження runtime, а також `providerAuthChoices` для дешевих - міток onboarding/auth-choice і метаданих прапорців CLI до завантаження runtime -- хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- runtime-хуки: `normalizeModelId`, `normalizeTransport`, + до завантаження runtime, а також `providerAuthChoices` для дешевих міток + onboarding/вибору auth і метаданих прапорців CLI до завантаження runtime +- гачки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- гачки runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -637,86 +637,86 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw усе ще володіє узагальненим циклом агента, failover, обробкою transcript і -політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, без -потреби в цілому custom inference transport. +OpenClaw і далі володіє загальним циклом агента, резервним переключенням, обробкою транскриптів і +політикою інструментів. Ці гачки є поверхнею розширення для специфічної для провайдера поведінки без +потреби в повністю власному транспорті інференсу. -Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має env-based credentials, -які загальні шляхи auth/status/model-picker повинні бачити без завантаження runtime плагіна. -Використовуйте `providerAuthChoices` у маніфесті, коли поверхні onboarding/auth-choice CLI -повинні знати id вибору провайдера, мітки груп і просту auth-wiring через один прапорець +Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, +які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime плагіна. +Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI onboarding/auth-choice +мають знати id вибору провайдера, мітки груп і просте підключення auth одним прапорцем без завантаження runtime провайдера. Зберігайте runtime `envVars` провайдера для -операторських підказок, як-от мітки onboarding або змінні налаштування OAuth -client-id/client-secret. +операторських підказок, таких як мітки onboarding або змінні налаштування +OAuth client-id/client-secret. -Використовуйте `channelEnvVars` у маніфесті, коли канал має auth або setup на основі env, -які загальний shell-env fallback, перевірки config/status або запити налаштування мають бачити -без завантаження runtime каналу. +Використовуйте маніфест `channelEnvVars`, коли канал має auth або setup на основі env, +які загальні шляхи резервного shell-env, перевірки config/status або підказки setup +мають бачити без завантаження runtime каналу. -### Порядок хуків і використання +### Порядок гачків і спосіб використання -Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий орієнтир для прийняття рішень. +Для плагінів моделей/провайдерів OpenClaw викликає гачки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий посібник для прийняття рішення. -| # | Хук | Що він робить | Коли використовувати | +| # | Гачок | Що він робить | Коли використовувати | | --- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями `base URL` за замовчуванням | +| 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` сімейства провайдера до загального збирання моделі | Провайдер володіє очищенням transport для custom id провайдерів у тому самому сімействі transport | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібно очищення конфігурації, яке має жити разом із плагіном; вбудовані helper для сімейства Google також підтримують сумісні записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурованих провайдерів | Провайдеру потрібні endpoint-driven виправлення метаданих native streaming usage | -| 7 | `resolveConfigApiKey` | Визначає auth env-marker для config providers до завантаження runtime auth | Провайдер має власне визначення API-key env-marker; `amazon-bedrock` також має вбудований AWS env-marker resolver тут | -| 8 | `resolveSyntheticAuth` | Виводить local/self-hosted або config-backed auth без збереження plaintext | Провайдер може працювати із synthetic/local маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає provider-owned зовнішні профілі auth; типове `persistence` — `runtime-only` для creds, що належать CLI/app | Провайдер повторно використовує зовнішні auth credentials без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені synthetic placeholder profiles нижче за auth на основі env/config-backed | Провайдер зберігає synthetic placeholder profiles, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний fallback для provider-owned model id, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний warm-up, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані до визначення невідомих id | -| 13 | `normalizeResolvedModel` | Остаточне переписування до того, як embedded runner використає визначену модель | Провайдеру потрібні переписування transport, але він усе ще використовує transport core | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для vendor-models за іншим сумісним transport | Провайдер розпізнає власні моделі на proxy transport без перехоплення провайдера | -| 15 | `capabilities` | Метадані transcript/tooling, що належать провайдеру та використовуються спільною логікою core | Провайдеру потрібні особливості transcript/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства transport | -| 17 | `inspectToolSchemas` | Показує provider-owned діагностику схем після нормалізації | Провайдер хоче попереджень щодо ключових слів без навчання core provider-specific правилам | -| 18 | `resolveReasoningOutputMode` | Вибирає нативний чи tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native fields | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних wrapper для stream options | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream custom transport-ом | Провайдеру потрібен custom wire protocol, а не просто wrapper | -| 21 | `wrapStreamFn` | Wrapper stream після застосування загальних wrapper | Провайдеру потрібні wrapper для сумісності заголовків/тіла запиту/моделі без custom transport | -| 22 | `resolveTransportTurnState` | Прикріплює native per-turn transport headers або метадані | Провайдер хоче, щоб загальні transport надсилали provider-native turn identity | -| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native WebSocket headers або політику cool-down сесії | Провайдер хоче, щоб загальні WS transport налаштовували заголовки сесії або політику fallback | -| 24 | `formatApiKey` | Форматувач auth-profile: збережений profile стає runtime-рядком `apiKey` | Провайдер зберігає додаткові auth-метадані і потребує custom форми runtime token | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для custom refresh endpoint або політики помилки оновлення | Провайдер не відповідає спільним refreshers `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли оновлення OAuth не вдається | Провайдеру потрібна власна підказка відновлення auth після помилки оновлення | -| 27 | `matchesContextOverflowError` | Визначення provider-owned переповнення контекстного вікна | Провайдер має сирі помилки переповнення, які загальні евристики не розпізнають | -| 28 | `classifyFailoverReason` | Класифікація причини failover, що належить провайдеру | Провайдер може зіставити сирі помилки API/transport із rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul провайдерів | Провайдеру потрібне proxy-specific керування cache TTL | -| 30 | `buildMissingAuthMessage` | Замінник загального повідомлення про відновлення після відсутності auth | Провайдеру потрібна provider-specific підказка відновлення при відсутності auth | -| 31 | `suppressBuiltInModel` | Приховування застарілої upstream-моделі плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх vendor-підказкою | -| 32 | `augmentModelCatalog` | Синтетичні/остаточні рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic forward-compat rows у `models list` і picker-ах | -| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер підтримує лише двійкове увімк./вимк. thinking | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(це не гачок плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми id моделі перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує сімейство провайдера `api` / `baseUrl` перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурацій провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від endpoint | +| 7 | `resolveConfigApiKey` | Визначає env-marker auth для конфігураційних провайдерів до завантаження runtime auth | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker | +| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; значення `persistence` за замовчуванням — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Понижує збережені синтетичні заповнювачі профілів нижче auth на основі env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають мати пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний варіант для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей | +| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого знову запускається `resolveDynamicModel` | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт core | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе провайдера | +| 15 | `capabilities` | Метадані транскриптів/інструментарію, що належать провайдеру та використовуються спільною логікою core | Провайдеру потрібні особливості транскриптів/сімейства провайдерів | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання core правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла/сумісності моделей без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Приєднує native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Приєднує native WebSocket-заголовки або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного вибору | +| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові метадані auth і потребує користувацької форми runtime-токена | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких endpoint оновлення або політики помилки оновлення | Провайдер не вписується у спільні засоби оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка виправлення, яка додається, коли оновлення OAuth не вдається | Провайдеру потрібні власні рекомендації з виправлення auth після помилки оновлення | +| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропускають | +| 28 | `classifyFailoverReason` | Класифікація причин резервного переключення, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відновлення після відсутньої auth | Провайдеру потрібна специфічна для провайдера підказка про відновлення auth | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою постачальника | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і в пікерах | +| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер надає лише бінарне thinking увімк./вимк. | | 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key безпосередньо перед inference | Провайдеру потрібен обмін token або короткоживучі request credentials | -| 38 | `resolveUsageAuth` | Визначає credentials використання/білінгу для `/usage` і пов’язаних status-surface | Провайдеру потрібен custom парсинг usage/quota token або інші credentials використання | -| 39 | `fetchUsageSnapshot` | Отримує і нормалізує provider-specific знімки usage/quota після визначення auth | Провайдеру потрібен provider-specific endpoint використання або parser payload | -| 40 | `createEmbeddingProvider` | Створює embedding-adapter, що належить провайдеру, для memory/search | Поведінка memory embedding має належати плагіну провайдера | -| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для провайдера | Провайдеру потрібна custom transcript policy (наприклад видалення thinking-block) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні provider-specific переписування replay понад спільні helper compaction | -| 43 | `validateReplayTurns` | Остаточна перевірка або переформатування turn replay перед embedded runner | Transport провайдера потребує суворішої перевірки turn після загальної санітизації | -| 44 | `onModelSelected` | Виконує provider-owned побічні ефекти після вибору моделі | Провайдеру потрібна телеметрія або provider-owned стан, коли модель стає активною | +| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | +| 36 | `isModernModelRef` | Матчер сучасних моделей для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед інференсом | Провайдеру потрібен обмін токенів або короткоживучі облікові дані запиту | +| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен користувацький парсинг токена usage/quota або інші облікові дані usage | +| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки usage/quota після визначення auth | Провайдеру потрібен специфічний endpoint usage або парсер корисного навантаження | +| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding у пам’яті має належати плагіну провайдера | +| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення thinking-блоків) | +| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні засоби компактування | +| 43 | `validateReplayTurns` | Остаточна перевірка або зміна форми ходів replay перед embedded runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санації | +| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -плагін провайдера, що збігся, а потім переходять до інших hook-capable provider plugins, -доки один із них справді не змінить id моделі або transport/config. Це дозволяє -shim-ам alias/compat провайдера працювати без вимоги до викликуча знати, який -вбудований плагін володіє переписуванням. Якщо жоден хук провайдера не переписує -підтримуваний запис конфігурації сімейства Google, вбудований normalizer конфігурації Google -усе одно застосовує це очищення сумісності. +відповідний плагін провайдера, а потім переходять до інших плагінів провайдерів, які підтримують гачки, +доки один із них справді не змінить id моделі або transport/config. Це зберігає +працездатність shim-плагінів alias/compat без вимоги до виклику знати, який саме +вбудований плагін володіє переписуванням. Якщо жоден гачок провайдера не переписує підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно +застосує це очищення сумісності. -Якщо провайдеру потрібен повністю custom wire protocol або custom request executor, -це інший клас розширення. Ці хуки — для поведінки провайдера, яка все ще -працює на звичайному циклі inference OpenClaw. +Якщо провайдеру потрібен повністю користувацький wire protocol або власний виконавець запитів, +це інший клас розширення. Ці гачки призначені для поведінки провайдера, +яка все ще виконується в межах звичайного циклу інференсу OpenClaw. ### Приклад провайдера @@ -776,114 +776,117 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - і `wrapStreamFn`, тому що володіє forward-compat для Claude 4.6, - підказками сімейства провайдера, вказівками з відновлення auth, інтеграцією endpoint використання, - допустимістю prompt-cache, типовими конфігураціями з урахуванням auth, політикою - thinking за замовчуванням/адаптивного thinking для Claude, а також provider-specific stream shaping для - beta headers, `/fast` / `serviceTier` і `context1m`. -- Stream-helpers Anthropic, специфічні для Claude, поки що залишаються у власному - публічному seam `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета + `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` + і `wrapStreamFn`, оскільки володіє forward-compat для Claude 4.6, + підказками сімейства провайдерів, рекомендаціями з виправлення auth, інтеграцією з endpoint usage, + відповідністю prompt-cache, значеннями конфігурації за замовчуванням з урахуванням auth, + політикою thinking за замовчуванням/адаптивного thinking для Claude + та специфічним для Anthropic формуванням потоку для + beta-заголовків, `/fast` / `serviceTier` і `context1m`. +- Допоміжні засоби потоку, специфічні для Claude в Anthropic, поки що залишаються у власних + публічних seams `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі - builders wrapper Anthropic замість розширення загального SDK навколо правил - beta-header одного провайдера. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і допоміжні + засоби побудови обгорток Anthropic нижчого рівня замість розширення загального SDK + навколо правил beta-заголовків одного провайдера. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - тому що володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI + оскільки володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приглушенням Spark, synthetic OpenAI list rows та політикою GPT-5 thinking / - live-model; сімейство stream `openai-responses-defaults` володіє - спільними native wrapper OpenAI Responses для attribution headers, - `/fast`/`serviceTier`, текстової verbosity, native Codex web search, - shaping payload reasoning-compat та керування контекстом Responses. + приглушенням Spark, синтетичними рядками списку OpenAI та політикою GPT-5 thinking / + live-моделей; сімейство потоків `openai-responses-defaults` володіє + спільними native-обгортками OpenAI Responses для заголовків атрибуції, + `/fast`/`serviceTier`, деталізації тексту, native веб-пошуку Codex, + формуванням payload reasoning-compat та керуванням контекстом Responses. - OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, тому що провайдер є pass-through і може відкривати нові - model id до оновлення статичного каталогу OpenClaw; він також використовує + `prepareDynamicModel`, оскільки провайдер є pass-through і може відкривати нові + id моделей до оновлення статичного каталогу OpenClaw; він також використовує `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати - заголовки запитів, метадані маршрутизації, патчі reasoning і політику - prompt-cache, специфічні для провайдера, поза core. Його політика replay походить із - сімейства `passthrough-gemini`, а сімейство stream `openrouter-thinking` - володіє proxy-ін’єкцією reasoning та пропусками для непідтримуваних моделей / `auto`. + специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і + політику prompt-cache поза core. Його політика replay походить із сімейства + `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` + володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому - потрібні device login, що належить провайдеру, поведінка fallback моделі, - особливості transcript Claude, обмін токена GitHub на токен Copilot і endpoint використання, що належить провайдеру. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки + йому потрібні власний device login, поведінка резервного вибору моделі, + особливості транскриптів Claude, обмін токена GitHub на токен Copilot + і власний endpoint usage. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він - усе ще працює на транспорті core OpenAI, але володіє своєю - нормалізацією transport/base URL, політикою fallback для оновлення OAuth, вибором - transport за замовчуванням, synthetic catalog rows Codex та інтеграцією endpoint використання ChatGPT; - він ділить те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI. + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки + він і далі працює на core-транспортах OpenAI, але володіє нормалізацією + transport/base URL, політикою резервного оновлення 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, - нативною перевіркою replay Gemini, bootstrap sanitation replay, режимом - tagged reasoning-output та зіставленням modern-model, тоді як - сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки + сімейство replay `google-gemini` володіє резервним варіантом forward-compat для Gemini 3.1, + native-перевіркою replay Gemini, санацією replay початкового завантаження, + режимом виводу reasoning з тегами та зіставленням сучасних моделей, тоді як + сімейство потоків `google-thinking` володіє нормалізацією payload thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токенів, парсингу токенів і підключення endpoint квоти. + `fetchUsageSnapshot` для форматування токенів, парсингу токенів і підключення + endpoint квот. - Anthropic Vertex використовує `buildReplayPolicy` через сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося - обмеженим id Claude, а не кожним transport `anthropic-messages`. + прив’язаним до id Claude, а не до кожного транспорту `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, для трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий - guard тільки для Claude `anthropic-by-model`. + guard `anthropic-by-model`, лише для Claude. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, тому що вони проксіюють Gemini - моделі через OpenAI-compatible transport і потребують sanitation - thought-signature Gemini без нативної перевірки replay Gemini чи bootstrap-переписувань. + через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini + через транспорти, сумісні з OpenAI, і потребують санації підпису думок Gemini + без native-перевірки replay Gemini або переписування початкового завантаження. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один провайдер володіє як - семантикою Anthropic-message, так і OpenAI-compatible; він зберігає - видалення thinking-block лише для Claude на боці Anthropic, одночасно перевизначаючи - режим reasoning output назад на native, а сімейство stream `minimax-fast-mode` володіє - переписуваннями fast-mode моделей на спільному шляху stream. -- Moonshot використовує `catalog` плюс `wrapStreamFn`, тому що він усе ще використовує - спільний transport OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; - сімейство stream `moonshot-thinking` відображає config плюс стан `/think` на - його native payload binary thinking. + сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє і + семантикою повідомлень Anthropic, і семантикою, сумісною з OpenAI; він зберігає + видалення thinking-блоків лише для Claude на стороні Anthropic, водночас перевизначаючи режим + виводу reasoning назад на native, а сімейство потоків `minimax-fast-mode` володіє + переписуванням моделей fast-mode на спільному шляху потоку. +- Moonshot використовує `catalog`, а також `wrapStreamFn`, оскільки він усе ще використовує спільний + транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; + сімейство потоків `moonshot-thinking` зіставляє config плюс стан `/think` зі своїм + native payload binary thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні provider-owned request headers, - нормалізація payload reasoning, підказки transcript Gemini і керування - Anthropic cache-TTL; сімейство stream `kilocode-thinking` зберігає ін’єкцію - Kilo thinking на шляху спільного proxy stream, пропускаючи `kilo/auto` та - інші proxy model id, які не підтримують явний payload reasoning. + `isCacheTtlEligible`, оскільки йому потрібні заголовки запитів, що належать провайдеру, + нормалізація payload reasoning, підказки транскриптів Gemini і + обмеження Anthropic cache-TTL; сімейство потоків `kilocode-thinking` зберігає ін’єкцію + thinking Kilo на спільному шляху proxy-потоку, водночас пропускаючи `kilo/auto` та + інші proxy-id моделей, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback GLM-5, - значеннями за замовчуванням `tool_stream`, UX binary thinking, зіставленням modern-model, а також - і auth використання, і отриманням квоти; сімейство stream `tool-stream-default-on` - тримає wrapper `tool_stream`, увімкнений за замовчуванням, поза handwritten glue окремих провайдерів. + `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє резервним варіантом GLM-5, + значеннями `tool_stream` за замовчуванням, UX бінарного thinking, зіставленням сучасних моделей + та і auth для usage, і отриманням квот; сімейство потоків `tool-stream-default-on` + тримає обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним glue + для окремих провайдерів. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - тому що володіє нормалізацією native xAI Responses transport, переписуванням - псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, - повторним використанням fallback auth для інструментів, що належать плагіну, визначенням моделі - Grok для forward-compat і provider-owned compat patches, як-от профіль схеми - інструментів xAI, непідтримувані ключові слова схеми, native `web_search` та декодування - аргументів виклику інструмента з HTML-entity. + оскільки володіє нормалізацією native xAI Responses transport, переписуванням псевдонімів + Grok fast-mode, `tool_stream` за замовчуванням, очищенням strict-tool / reasoning-payload, + повторним використанням резервної auth для інструментів, що належать плагіну, визначенням + моделей Grok з forward-compat і compat-патчами, що належать провайдеру, такими як профіль + схем інструментів xAI, непідтримувані ключові слова схеми, native `web_search` та декодування + аргументів виклику інструментів із HTML-entity. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - тримати особливості transcript/tooling поза core. -- Вбудовані провайдери лише з каталогом, як-от `byteplus`, `cloudflare-ai-gateway`, + тримати особливості транскриптів/інструментарію поза core. +- Каталогові вбудовані провайдери, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. - Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації - media-understanding і video-generation для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, тому що їхня поведінка - `/usage` належить плагіну, навіть хоча inference усе ще виконується через спільні - transport. + розуміння медіа й генерації відео для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog` плюс гачки usage, оскільки їхня поведінка `/usage` + належить плагіну, навіть попри те, що інференс усе ще виконується через спільні транспорти. -## Runtime-helpers +## Допоміжні засоби середовища виконання -Плагіни можуть отримувати доступ до вибраних helper core через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -904,14 +907,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload виводу TTS core для поверхонь файлів/голосових нотаток. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS із core для поверхонь файлів/голосових повідомлень. - Використовує конфігурацію core `messages.tts` і вибір провайдера. -- Повертає PCM audio buffer + sample rate. Плагіни мають ресемплювати/кодувати для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для vendor-owned picker-ів голосів або потоків налаштування. -- Списки голосів можуть містити багатші метадані, як-от locale, gender і теги personality для picker-ів, обізнаних про провайдера. -- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни мають виконувати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для вибору голосів, що належать постачальнику, або потоків setup. +- Списки голосів можуть містити багатші метадані, такі як мова, стать і теги особистості для вибору, орієнтованого на провайдера. +- Сьогодні телефонію підтримують OpenAI і ElevenLabs. Microsoft — ні. -Плагіни також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -931,15 +934,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповіді в core. -- Використовуйте speech providers для поведінки синтезу, що належить вендору. -- Застаріле значення Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один vendor-плагін може - володіти текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw - додає ці контракти можливостей. +- Зберігайте політику TTS, резервний вибір і доставку відповідей у core. +- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику. +- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один vendor-плагін може володіти + текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру додавання + OpenClaw контрактів цих можливостей. Для розуміння зображень/аудіо/відео плагіни реєструють один типізований -media-understanding provider замість загального key/value bag: +провайдер розуміння медіа замість узагальненого набору ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -953,16 +956,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, конфігурацію і wiring каналів у core. -- Зберігайте поведінку вендора в плагіні провайдера. +- Зберігайте оркестрацію, резервний вибір, конфігурацію та підключення каналів у core. +- Зберігайте поведінку постачальника в плагіні провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та runtime-helper + - core володіє контрактом можливості та допоміжним засобом середовища виконання - vendor-плагіни реєструють `api.registerVideoGenerationProvider(...)` - - feature/channel plugins споживають `api.runtime.videoGeneration.*` + - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для runtime-helpers media-understanding плагіни можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -977,27 +980,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо плагіни можуть використовувати або runtime media-understanding, -або старіший псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або середовище виконання розуміння медіа, +або старий псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // Необов’язково, коли MIME не вдається надійно визначити: mime: "audio/ogg", }); ``` Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна surface для +- `api.runtime.mediaUnderstanding.*` — бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо core media-understanding (`tools.media.audio`) і порядок fallback провайдера. -- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад через пропущене/непідтримуване введення). +- Використовує конфігурацію аудіо розуміння медіа core (`tools.media.audio`) і порядок резервного вибору провайдерів. +- Повертає `{ text: undefined }`, якщо вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу). - `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. -Плагіни також можуть запускати фонові підзапуски subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові підагентні виконання через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1011,14 +1014,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. -- OpenClaw враховує ці поля перевизначення лише для trusted callers. -- Для fallback-запусків, що належать плагіну, оператори мають явно погодитися через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити trusted plugins конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски subagent із недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу на fallback. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. +- OpenClaw застосовує ці поля перевизначення лише для довірених викликачів. +- Для резервних запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни певними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. +- Недовірені запуски підагентів із плагінів теж працюють, але запити на перевизначення відхиляються, а не тихо переводяться на резервний варіант. -Для веб-пошуку плагіни можуть споживати спільний runtime-helper замість -звернення до wiring інструмента агента: +Для веб-пошуку плагіни можуть використовувати спільний допоміжний засіб середовища виконання +замість звернення до підключення інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1034,14 +1037,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати провайдери веб-пошуку через +Плагіни також можуть реєструвати провайдерів веб-пошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, визначення credential і спільну семантику запитів у core. -- Використовуйте провайдери веб-пошуку для vendor-specific пошукових transport. -- `api.runtime.webSearch.*` — це бажана спільна surface для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від wrapper інструмента агента. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core. +- Використовуйте провайдерів веб-пошуку для транспортів пошуку, специфічних для постачальника. +- `api.runtime.webSearch.*` — бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1057,11 +1060,11 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічити доступних провайдерів генерації зображень та їхні можливості. +- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. ## HTTP-маршрути Gateway -Плагіни можуть відкривати HTTP endpoints за допомогою `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP endpoint-и через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1079,33 +1082,33 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язково. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, якими керує плагін. -- `match`: необов’язково. `"exact"` (типово) або `"prefix"`. +- `auth`: обов’язково. Використовуйте `"gateway"` для вимоги звичайної auth gateway або `"plugin"` для auth/перевірки webhook, якими керує плагін. +- `match`: необов’язково. `"exact"` (за замовчуванням) або `"prefix"`. - `replaceExisting`: необов’язково. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. -- `handler`: повертає `true`, коли маршрут обробив запит. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено і воно спричинить помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. -- Маршрути плагінів повинні явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо тільки не встановлено `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Маршрути, що перекриваються і мають різні рівні `auth`, відхиляються. Зберігайте ланцюги проходження `exact`/`prefix` лише на одному рівні auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для webhook/signature verification, якими керує плагін, а не для привілейованих helper-викликів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний: - - 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-surface. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте auth-режим із передачею ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути плагінів мають явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не встановлено `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюги проходження `exact`/`prefix` мають бути лише на одному рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/перевірки підпису, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. +- Маршрути `auth: "gateway"` виконуються в межах області runtime запиту Gateway, але ця область навмисно є консервативною: + - bearer-аутентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів плагінів на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів плагіна з ідентичністю, область runtime повертається до `operator.write` +- Практичне правило: не вважайте маршрут плагіна з gateway-auth неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з носієм ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. -## Шляхи імпорту SDK плагінів +## Шляхи імпорту Plugin SDK -Під час написання плагінів використовуйте subpath 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` (`OpenClawSchema`). -- Стабільні примітиви каналів, як-от `openclaw/plugin-sdk/channel-setup`, +- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1117,17 +1120,18 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного wiring - setup/auth/reply/webhook. `channel-inbound` — це спільний дім для - debounce, зіставлення згадок, helper-ів політики згадок для inbound, форматування envelope та helper-ів контексту inbound envelope. - `channel-setup` — це вузький seam налаштування для необов’язкового встановлення. - `setup-runtime` — це runtime-safe surface налаштування, яку використовує `setupEntry` / - відкладений запуск, включно з import-safe setup patch adapters. - `setup-adapter-runtime` — це env-aware seam account-setup adapter. - `setup-tools` — це малий seam helper-ів для CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` для спільного підключення + setup/auth/reply/webhook. `channel-inbound` — це спільний дім для debounce, зіставлення згадок, + допоміжних засобів політики згадок у вхідних повідомленнях, форматування конвертів і + допоміжних засобів контексту вхідних конвертів. + `channel-setup` — це вузький seam setup з необов’язковим встановленням. + `setup-runtime` — це безпечна для runtime поверхня setup, що використовується `setupEntry` / + відкладеним запуском, включно з адаптерами патчів setup, безпечними для імпорту. + `setup-adapter-runtime` — це seam env-aware адаптера налаштування облікового запису. + `setup-tools` — це невеликий seam допоміжних засобів CLI/архівів/документації (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Domain-subpath, як-от `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`, @@ -1142,136 +1146,135 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних helper-ів runtime/config. - `telegram-command-config` — це вузький публічний seam для нормалізації/валідації custom - команд Telegram і він залишається доступним навіть якщо surface контракту вбудованого - Telegram тимчасово недоступна. - `text-runtime` — це спільний seam text/markdown/logging, включно з - видаленням text, видимого помічнику, helper-ами render/chunking markdown, helper-ами - редагування, helper-ами directive-tag і утилітами safe-text. -- Approval-specific channel seams мають віддавати перевагу одному контракту - `approvalCapability` у плагіні. Тоді core читає auth, доставку, рендеринг і - поведінку native-routing для approval через цю одну можливість, замість змішування - поведінки approval із не пов’язаними полями плагіна. -- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як - compat shim для старіших плагінів. Новий код має імпортувати вужчі - загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього + `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config. + `telegram-command-config` — це вузький публічний seam для нормалізації/валідації + користувацьких команд Telegram і він залишається доступним, навіть якщо поверхня контракту + вбудованого Telegram тимчасово недоступна. + `text-runtime` — це спільний seam text/markdown/logging, зокрема + видалення тексту, видимого асистенту, допоміжні засоби рендерингу/фрагментації markdown, редагування, + допоміжні засоби тегів директив і безпечний текст. +- Для специфічних каналів seam-ів схвалення слід надавати перевагу одному контракту + `approvalCapability` на плагіні. Тоді core читає auth, доставку, рендеринг і + native-routing для схвалення через цю одну можливість замість змішування + поведінки схвалення з не пов’язаними полями плагіна. +- `openclaw/plugin-sdk/channel-runtime` є застарілим і зберігається лише як + shim сумісності для старіших плагінів. Новий код має імпортувати вужчі + загальні примітиви, і код репозиторію не повинен додавати нові імпорти цього shim. -- Внутрішня будова вбудованих розширень залишається приватною. Зовнішні плагіни повинні використовувати лише subpath `openclaw/plugin-sdk/*`. Код core/test OpenClaw може використовувати - публічні entry point репозиторію під коренем пакета плагіна, як-от `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` і вузько спрямовані файли, як-от +- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/тестів OpenClaw може використовувати + публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` і вузькоспрямовані файли, як-от `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з іншого розширення. -- Поділ entry point репозиторію: - `/api.js` — це barrel helper-ів/типів, - `/runtime-api.js` — це barrel лише для runtime, - `/index.js` — це entry вбудованого плагіна, - а `/setup-entry.js` — це entry setup-плагіна. +- Поділ точок входу репозиторію: + `/api.js` — панель допоміжних засобів/типів, + `/runtime-api.js` — панель лише для runtime, + `/index.js` — точка входу вбудованого плагіна, + а `/setup-entry.js` — точка входу setup-плагіна. - Поточні приклади вбудованих провайдерів: - - Anthropic використовує `api.js` / `contract-api.js` для helper-ів stream Claude, як-от - `wrapAnthropicProviderStream`, helper-ів beta-header і парсингу `service_tier`. - - OpenAI використовує `api.js` для builder-ів провайдера, helper-ів моделей за замовчуванням і - builder-ів realtime provider. - - OpenRouter використовує `api.js` для свого builder провайдера плюс helper-ів - onboarding/config, тоді як `register.runtime.js` усе ще може повторно експортувати - загальні helper-и `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні entry point, завантажені через facade, віддають перевагу активному знімку конфігурації runtime, - коли він існує, а інакше повертаються до визначеного файла конфігурації на диску, коли - OpenClaw ще не надає runtime snapshot. + - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких + як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`. + - OpenAI використовує `api.js` для builder-ів провайдера, допоміжних засобів моделі за замовчуванням і + builder-ів провайдера реального часу. + - OpenRouter використовує `api.js` для свого builder-а провайдера, а також допоміжних засобів onboarding/config, + тоді як `register.runtime.js` усе ще може повторно експортувати загальні + допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні точки входу, завантажувані через facade, надають перевагу активному знімку конфігурації runtime, + якщо він існує, а потім повертаються до визначеного файла конфігурації на диску, коли + OpenClaw ще не надає знімок runtime. - Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований compat-набір helper seams під брендами вбудованих каналів усе ще - існує. Розглядайте їх як seams для супроводу/сумісності вбудованих плагінів, а не як - нові цілі імпорту для сторонніх розробників; нові міжканальні контракти, як і раніше, мають - потрапляти до загальних subpath `plugin-sdk/*` або до локальних barrel `api.js` / - `runtime-api.js` самого плагіна. + зарезервований набір seams з брендингом вбудованих каналів для сумісності все ще існує. + Розглядайте їх як seams для обслуговування/сумісності вбудованих компонентів, а не як нові цілі імпорту для сторонніх плагінів; нові міжканальні контракти все одно мають + потрапляти в загальні підшляхи `plugin-sdk/*` або локальні панелі `api.js` / + `runtime-api.js` плагіна. Примітка щодо сумісності: -- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. -- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші subpath +- Уникайте кореневої панелі `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 action і helper-и message-id для реакцій належать до + allowlist/status/message-tool — це бажаний контракт для нової роботи + з вбудованими та зовнішніми плагінами. + Парсинг/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`. + Шлюзи дій повідомлень і допоміжні засоби id повідомлень для реакцій мають належати `openclaw/plugin-sdk/channel-actions`. -- Helper-barrel-ів, специфічних для вбудованих розширень, типово не слід вважати стабільними. Якщо - helper потрібен лише вбудованому розширенню, залишайте його за локальним - seam `api.js` або `runtime-api.js` цього розширення замість просування до +- Панелі допоміжних засобів, специфічні для вбудованих розширень, не є стабільними за замовчуванням. Якщо + допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальним seam + `api.js` або `runtime-api.js` цього розширення замість винесення в `openclaw/plugin-sdk/`. -- Нові seams спільних helper-ів повинні бути загальними, а не брендованими під канал. - Спільний парсинг цілей належить до `openclaw/plugin-sdk/channel-targets`; channel-specific - внутрішня логіка залишається за локальним seam `api.js` або `runtime-api.js` - відповідного плагіна. -- Capability-specific subpath, як-от `image-generation`, - `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни - використовують їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є - довгостроковим незмінним зовнішнім контрактом. +- Нові seams спільних допоміжних засобів мають бути загальними, а не брендовими для каналу. Спільний парсинг цілей + належить `openclaw/plugin-sdk/channel-targets`; специфічні для каналу + внутрішні компоненти залишаються за локальним seam `api.js` або `runtime-api.js` + плагіна-власника. +- Підшляхи, специфічні для можливостей, такі як `image-generation`, + `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують + їх сьогодні. Їх наявність сама по собі не означає, що кожен експортований допоміжний засіб є + довгостроковим зафіксованим зовнішнім контрактом. ## Схеми інструмента повідомлень -Плагіни повинні володіти channel-specific внесками до схем `describeMessageTool(...)`. -Зберігайте поля, специфічні для провайдера, у плагіні, а не у спільному core. +Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу. +Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному core. -Для спільних portable-фрагментів схем повторно використовуйте загальні helper-и, експортовані через +Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованого payload картки +- `createMessageToolButtonsSchema()` для корисного навантаження у стилі сітки кнопок +- `createMessageToolCardSchema()` для структурованого корисного навантаження карток -Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному -коді цього плагіна замість просування до спільного SDK. +Якщо форма схеми має сенс лише для одного провайдера, визначайте її у вихідному коді +цього плагіна, а не виносьте до спільного SDK. -## Визначення цілей каналу +## Визначення цілі каналу -Плагіни каналів повинні володіти channel-specific семантикою цілей. Зберігайте -спільний outbound host узагальненим і використовуйте surface messaging adapter для правил провайдера: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Тримайте спільний +outbound host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: -- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль слід - трактувати як `direct`, `group` або `channel` до пошуку в directory. +- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль + слід вважати `direct`, `group` або `channel` до пошуку в каталозі. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - введення слід одразу скерувати на визначення, подібне до id, замість пошуку в directory. -- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли - core потребує остаточного provider-owned визначення після нормалізації або після - промаху в directory. -- `messaging.resolveOutboundSessionRoute(...)` володіє provider-specific побудовою маршруту сесії + слід для вводу одразу перейти до визначення за схожістю на id замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` — це резервний варіант плагіна, коли + core потребує фінального визначення, що належить провайдеру, після нормалізації або після + промаху каталогу. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту outbound-сесії, специфічною для провайдера, після визначення цілі. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають прийматися до - пошуку peers/groups. -- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/native target id». -- Використовуйте `resolveTarget` для provider-specific fallback нормалізації, а не для - широкого пошуку в directory. -- Зберігайте provider-native id, як-от id чатів, id гілок, JID, handles та id кімнат, - усередині значень `target` або provider-specific params, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають прийматися до + пошуку однолітків/груп. +- Використовуйте `looksLikeId` для перевірок «розглядати це як явний/native id цілі». +- Використовуйте `resolveTarget` для специфічного для провайдера резервного варіанту нормалізації, а не для + широкого пошуку в каталозі. +- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle і room id, + усередині значень `target` або в параметрах, специфічних для провайдера, а не в загальних полях SDK. ## Каталоги на основі конфігурації -Плагіни, які виводять записи directory із конфігурації, повинні зберігати цю логіку в -плагіні та повторно використовувати спільні helper-и з +Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в +плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні записи directory на основі конфігурації, такі як: +Використовуйте це, коли каналу потрібні каталоги на основі конфігурації, наприклад: -- DM-peers на основі allowlist -- налаштовані відповідності каналу/групи -- статичні fallback directory, прив’язані до облікового запису +- DM-контакти, керовані allowlist +- налаштовані зіставлення каналів/груп +- резервні статичні каталоги в межах облікового запису -Спільні helper-и в `directory-runtime` обробляють лише загальні операції: +Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: - фільтрацію запитів -- застосування ліміту -- helper-и dedupe/normalization +- застосування обмежень +- допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Інспекція облікового запису та нормалізація id, специфічні для каналу, мають залишатися в -реалізації плагіна. +Перевірка облікових записів і нормалізація id, специфічні для каналу, мають залишатися +в реалізації плагіна. ## Каталоги провайдерів -Плагіни провайдерів можуть визначати каталоги моделей для inference за допомогою +Плагіни провайдерів можуть визначати каталоги моделей для інференсу за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -1280,60 +1283,58 @@ api.registerHttpRoute({ - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдерів -Використовуйте `catalog`, коли плагін володіє model id, значеннями base URL -за замовчуванням або auth-gated метаданими моделей, специфічними для провайдера. +Використовуйте `catalog`, коли плагін володіє специфічними для провайдера id моделей, значеннями base URL +за замовчуванням або метаданими моделей, що залежать від auth. -`catalog.order` керує тим, коли каталог плагіна об’єднується відносно -вбудованих неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих +неявних провайдерів OpenClaw: -- `simple`: провайдери зі звичайним API key або на основі env -- `profile`: провайдери, які з’являються, коли існують профілі auth -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера +- `simple`: звичайні провайдери з API-ключем або на основі env +- `profile`: провайдери, що з’являються, коли існують профілі auth +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають при конфлікті ключів, тож плагіни можуть навмисно +Пізніші провайдери виграють у разі конфлікту ключів, тому плагіни можуть навмисно перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` усе ще працює як застарілий псевдонім +- `discovery` і далі працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Канальний огляд лише для читання +## Канальна інспекція лише для читання -Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш плагін реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що credentials - повністю матеріалізовані, і швидко завершуватися з помилкою, коли потрібні секрети відсутні. -- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`, +- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні. +- Командні шляхи лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки - doctor/config repair, не повинні потребувати матеріалізації runtime credentials лише для + doctor/config repair, не повинні потребувати матеріалізації runtime-облікових даних лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Додає поля джерела/стану credentials, коли це доречно, наприклад: +- Включає поля джерела/стану облікових даних, коли це доречно, такі як: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для звітування про - доступність у режимі лише для читання. Достатньо повернути `tokenStatus: "available"` - (і відповідне поле джерела) для команд на кшталт status. -- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але - він недоступний у поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність у режимі лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але + вони недоступні в поточному шляху команди. Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштований. -## Пакети pack +## Пакетні набори -Каталог плагіна може містити `package.json` з `openclaw.extensions`: +Каталог плагіна може містити `package.json` із `openclaw.extensions`: ```json { @@ -1345,64 +1346,60 @@ api.registerHttpRoute({ } ``` -Кожен entry стає плагіном. Якщо pack містить кілька extensions, id плагіна +Кожен запис стає плагіном. Якщо пакет перераховує кілька розширень, id плагіна стає `name/`. -Якщо ваш плагін імпортує npm-залежності, встановіть їх у цьому каталозі, щоб +Якщо ваш плагін імпортує залежності npm, установіть їх у цьому каталозі, щоб `node_modules` були доступні (`npm install` / `pnpm install`). -Запобіжне правило безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна -після визначення символічних посилань. Entries, що виходять за межі каталогу пакета, -відхиляються. +Запобіжник безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна +після визначення символьних посилань. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies у runtime). Підтримуйте дерева залежностей плагіна -«чистими JS/TS» і уникайте пакетів, які потребують збірки через `postinstall`. +Зауваження щодо безпеки: `openclaw plugins install` установлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle-скриптів і без dev-залежностей під час runtime). Підтримуйте дерева залежностей плагіна як «чисті JS/TS» і уникайте пакетів, які потребують `postinstall`-збирань. Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потрібні surfaces setup для вимкненого плагіна каналу або -коли плагін каналу увімкнено, але ще не налаштовано, він завантажує `setupEntry` -замість повного entry плагіна. Це робить запуск і setup легшими, -коли ваш основний entry плагіна також підключає інструменти, хуки або інший код лише для runtime. +Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або +коли плагін каналу увімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повної точки входу плагіна. Це робить запуск і setup легшими, +коли ваша основна точка входу плагіна також підключає інструменти, гачки або інший код лише для runtime. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести плагін каналу на той самий шлях `setupEntry` під час фази -pre-listen запуску gateway, навіть якщо канал уже налаштовано. +може перевести плагін каналу на той самий шлях `setupEntry` на етапі запуску gateway +до початку прослуховування, навіть якщо канал уже налаштований. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває surface запуску, яка має існувати -до того, як gateway почне слухати. На практиці це означає, що entry setup -має зареєструвати кожну можливість каналу, від якої залежить запуск, наприклад: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати +до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup +має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: -- реєстрацію самого каналу +- саму реєстрацію каналу - будь-які HTTP-маршрути, які мають бути доступні до початку прослуховування gateway -- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому самому вікні часу +- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому ж часовому вікні -Якщо ваш повний entry усе ще володіє будь-якою необхідною можливістю запуску, не вмикайте -цей прапорець. Залиште плагін на типовій поведінці й дозвольте OpenClaw завантажити -повний entry під час запуску. +Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте +цей прапорець. Залиште плагін із типовою поведінкою й дозвольте OpenClaw завантажити +повну точку входу під час запуску. -Вбудовані канали також можуть публікувати helper-и surface контракту лише для setup, з якими core -може радитися до завантаження повного runtime каналу. Поточна surface просування setup: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, які core +може використовувати до завантаження повного runtime каналу. Поточна поверхня просування setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю surface, коли йому потрібно просунути застарілу конфігурацію -каналу з одним обліковим записом у `channels..accounts.*` без завантаження повного entry плагіна. -Поточний приклад вбудованого каналу — Matrix: він переміщує лише ключі auth/bootstrap у +Core використовує цю поверхню, коли потрібно просунути застарілу конфігурацію каналу з одним обліковим записом у +`channels..accounts.*` без завантаження повної точки входу плагіна. +Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap у іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість завжди створювати +зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці setup patch adapters зберігають lazy-виявлення surface контракту вбудованого плагіна. -Час імпорту залишається легким; surface просування завантажується лише під час першого -використання замість повторного входу у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів setup зберігають лінивий характер виявлення поверхні контракту вбудованих компонентів. Час імпорту залишається малим; поверхня просування завантажується лише під час першого використання замість повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці surfaces запуску містять методи Gateway RPC, зберігайте їх на -префіксі, специфічному для плагіна. Простори імен admin core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються -як `operator.admin`, навіть якщо плагін запитує вужчий scope. +Коли ці поверхні запуску включають gateway RPC-методи, тримайте їх на +префіксі, специфічному для плагіна. Простори імен адміністратора core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються +як `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -1421,8 +1418,8 @@ Core використовує цю surface, коли йому потрібно ### Метадані каталогу каналів -Плагіни каналів можуть рекламувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє core не містити даних каталогу. +Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє core не містити власних даних каталогу. Приклад: @@ -1437,7 +1434,7 @@ Core використовує цю surface, коли йому потрібно "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", + "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1450,22 +1447,22 @@ Core використовує цю surface, коли йому потрібно } ``` -Корисні поля `openclaw.channel` поза мінімальним прикладом: +Корисні поля `openclaw.channel`, крім мінімального прикладу: -- `detailLabel`: вторинна мітка для багатших surfaces каталогу/status -- `docsLabel`: перевизначити текст посилання на docs -- `preferOver`: id нижчопріоритетних plugin/channel, які цей запис каталогу повинен випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування текстом поверхні вибору -- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо outbound formatting -- `exposure.configured`: приховує канал із surfaces списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для surfaces навігації docs +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `docsLabel`: перевизначення тексту посилання на документацію +- `preferOver`: id плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування текстом поверхонь вибору +- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо форматування outbound +- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` +- `exposure.setup`: приховує канал із інтерактивних пікерів setup/configure, якщо встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддає перевагу lookup сесії під час визначення announce target +- `quickstartAllowFrom`: вмикає для каналу стандартний потік quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce-цілей -OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). Помістіть JSON-файл в одне з місць: - `~/.openclaw/mpm/plugins.json` @@ -1473,28 +1470,37 @@ OpenClaw також може об’єднувати **зовнішні ката - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має +один або кілька JSON-файлів (розділених комами/крапками з комою/роздільником `PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Плагіни контекстного рушія +## Плагіни рушія контексту -Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly -і compaction. Реєструйте їх зі свого плагіна через +Плагіни рушія контексту володіють оркестрацією контексту сесії для поглинання, +збирання та компактування. Реєструйте їх із вашого плагіна через `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати memory search або хуки. +конвеєр контексту, а не просто додати пошук у пам’яті чи гачки. ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function (api) { api.registerContextEngine("lossless-claw", () => ({ info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true }, async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact() { return { ok: true, compacted: false }; @@ -1503,11 +1509,14 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом compaction, залиште `compact()` +Якщо ваш рушій **не** володіє алгоритмом компактування, залиште `compact()` реалізованим і явно делегуйте його: ```ts -import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"; +import { + buildMemorySystemPromptAddition, + delegateCompactionToRuntime, +} from "openclaw/plugin-sdk/core"; export default function (api) { api.registerContextEngine("my-memory-engine", () => ({ @@ -1519,8 +1528,15 @@ export default function (api) { async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact(params) { return await delegateCompactionToRuntime(params); @@ -1532,44 +1548,44 @@ export default function (api) { ## Додавання нової можливості Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний reach-in. Додайте відсутню можливість. +систему плагінів через приватний прямий доступ. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політика, fallback, об’єднання конфігурації, - життєвий цикл, семантика для каналів і форма runtime-helper. -2. додайте типізовані surfaces реєстрації/runtime для плагіна + Вирішіть, якою спільною поведінкою має володіти core: політика, резервний вибір, злиття конфігурації, + життєвий цикл, семантика для каналів і форма допоміжного засобу runtime. +2. додайте типізовані поверхні реєстрації/runtime для плагіна Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. 3. підключіть споживачів core + каналів/функцій - Канали й плагіни функцій повинні споживати нову можливість через core, - а не через прямий імпорт реалізації вендора. -4. зареєструйте реалізації вендора - Потім vendor-плагіни реєструють свої бекенди для цієї можливості. -5. додайте contract coverage - Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. + Канали та плагіни функцій мають споживати нову можливість через core, + а не імпортувати реалізацію постачальника напряму. +4. зареєструйте реалізації постачальників + Тоді vendor-плагіни реєструють свої бекенди для цієї можливості. +5. додайте контрактне покриття + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до світогляду -одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного списку файлів і робочого прикладу. +Саме так OpenClaw зберігає власну думку, не стаючи жорстко прив’язаним до +світогляду одного провайдера. Див. [Практичний посібник із можливостей](/uk/plugins/architecture) +для конкретного списку файлів і опрацьованого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих -surface одночасно: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися +таких поверхонь: - типи контрактів core у `src//types.ts` -- runner/runtime-helper core у `src//runtime.ts` -- surface реєстрації API плагіна в `src/plugins/types.ts` -- wiring реєстру плагінів у `src/plugins/registry.ts` -- exposure runtime плагіна в `src/plugins/runtime/*`, коли feature/channel - plugins мають її споживати -- capture/test helpers у `src/test-utils/plugin-registration.ts` -- перевірки володіння/контрактів у `src/plugins/contracts/registry.ts` -- документацію для операторів/плагінів у `docs/` +- runner/допоміжний засіб runtime core у `src//runtime.ts` +- поверхня реєстрації API плагіна у `src/plugins/types.ts` +- підключення реєстру плагінів у `src/plugins/registry.ts` +- відкриття runtime плагіна у `src/plugins/runtime/*`, коли плагіни функцій/каналів + мають її споживати +- допоміжні засоби захоплення/тестування у `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту у `src/plugins/contracts/registry.ts` +- документація для операторів/плагінів у `docs/` -Якщо однієї з цих surfaces бракує, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1577,14 +1593,14 @@ surface одночасно: Мінімальний шаблон: ```ts -// core contract +// контракт core export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// plugin API +// API плагіна api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1593,22 +1609,22 @@ api.registerVideoGenerationProvider({ }, }); -// shared runtime helper for feature/channel plugins +// спільний допоміжний засіб runtime для плагінів функцій/каналів const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, }); ``` -Шаблон contract test: +Шаблон контрактного тесту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає правило простим: +Це зберігає просте правило: - core володіє контрактом можливості + оркестрацією -- vendor-плагіни володіють реалізаціями вендора -- feature/channel plugins споживають runtime-helpers -- contract tests зберігають володіння явним +- vendor-плагіни володіють реалізаціями постачальників +- плагіни функцій/каналів споживають допоміжні засоби runtime +- контрактні тести зберігають явність володіння diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 90fe86f6a..981dde3b6 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -4,27 +4,27 @@ read_when: - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-07T07:39:30Z" + generated_at: "2026-04-07T08:02:41Z" model: gpt-5.4 provider: openai - source_hash: 9f05178454058038cd69a58bc8392e2574a48a61fbaef9b7db9eba2ffa9f1374 + source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727 source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка є -довідником для **що імпортувати** і **що можна реєструвати**. +Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — +довідник про **що імпортувати** і **що можна зареєструвати**. - **Шукаєте практичний посібник?** + **Шукаєте покроковий посібник?** - Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Плагін каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Плагін провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Плагін каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Плагін провайдера? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins) ## Угода щодо імпорту @@ -37,38 +37,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і -запобігає проблемам із циклічними залежностями. Для специфічних до каналу -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` -залишайте для ширшої узагальненої поверхні та спільних допоміжних засобів, таких як +запобігає проблемам із циклічними залежностями. Для специфічних для каналу +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте +для ширшої узагальненої поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. -Не додавайте і не використовуйте зручні шви з іменами провайдерів, такі як +Не додавайте і не покладайтеся на зручні шви, названі на честь провайдерів, такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шви з брендингом каналу. Вбудовані плагіни мають компонувати -загальні підшляхи SDK всередині власних barrel-файлів `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці локальні для плагіна barrel-файли, або додавати вузький загальний SDK -контракт, коли потреба справді є міжканальною. +допоміжні шви з брендингом каналів. Вбудовані плагіни мають компонувати +загальні підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро +має або використовувати ці локальні для плагіна barrel-файли, або додати вузький загальний SDK +контракт, якщо потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір допоміжних +Згенерована карта експорту все ще містить невеликий набір допоміжних швів вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для супроводу вбудованих плагінів і сумісності; вони -навмисно не включені до загальної таблиці нижче і не є рекомендованим +підшляхи існують лише для підтримки та сумісності вбудованих плагінів; вони +навмисно пропущені в загальній таблиці нижче і не є рекомендованим шляхом імпорту для нових сторонніх плагінів. ## Довідник підшляхів Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із -понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`. +понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в цьому згенерованому списку. -Ставтеся до них як до поверхонь деталей реалізації/сумісності, якщо лише сторінка документації -явно не просуває один із них як публічний. +Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в цьому +згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності, якщо +сторінка документації явно не оголошує якийсь із них публічним. -### Вхідна точка плагіна +### Entry плагіна -| Підшлях | Ключові експорти | +| Підшлях | Ключові експорти | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -82,46 +82,46 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, побудовники статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку allowlist, збирачі статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби багатокористувацької конфігурації/керування шлюзами дій, допоміжні засоби резервного облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного вибору за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби списку облікових записів/дій облікових записів | + | `plugin-sdk/account-core` | Допоміжні засоби багатооблікового запису config/action-gate, допоміжні засоби резервного вибору типового облікового запису | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації id облікового запису | + | `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного вибору типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним використанням вбудованого контракту | + | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним варіантом для вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідного маршруту + envelope | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень + побудови envelope | | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних даних | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби ідентичності/делегування надсилання вихідних даних | - | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків і допоміжні засоби адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіапейлоаду агента | - | `plugin-sdk/conversation-runtime` | Прив’язка розмови/потоку, pairинг і допоміжні засоби налаштованих прив’язок | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби делегування вихідної ідентичності/надсилання | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків | + | `plugin-sdk/agent-media-payload` | Застарілий збирач медіапейлоаду агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмови/потоку, парування та налаштованих прив’язок | | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку статусу каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагіна каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагінів каналів | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо доступу до груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/редукції інтерактивних payload відповіді | - | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce вхідних даних, зіставлення згадок, політики згадок і допоміжні засоби envelope | - | `plugin-sdk/channel-send-result` | Типи результатів відповіді | + | `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту для прямих DM | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення інтерактивного reply payload | + | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce для вхідних повідомлень, зіставлення згадок, політики згадок і допоміжні засоби envelope | + | `plugin-sdk/channel-send-result` | Типи результату відповіді | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контрактів каналу | - | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | + | `plugin-sdk/channel-contract` | Типи контракту каналу | + | `plugin-sdk/channel-feedback` | Налаштування зворотного зв’язку/реакцій | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | @@ -129,131 +129,131 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | - | `plugin-sdk/cli-backend` | Значення за замовчуванням для CLI backend + константи watchdog | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для плагінів провайдерів | | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний побудовник OAuth auth-result | + | `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth-автентифікації | | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env-var для auth провайдера | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політики replay, допоміжні засоби endpoint провайдерів та допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі політик replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби для HTTP/endpoint можливостей провайдерів | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-сетери/гетери облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для web-search провайдерів | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу для web-fetch провайдера | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime для web-search провайдера | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення + діагностика схеми Gemini та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper та спільні допоміжні обгортки Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Допоміжні засоби внесення патчів до конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і auth дій у тому самому чаті | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення апрувера та авторизації дій у тому самому чаті | | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей native approval + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для exec/plugin approval | - | `plugin-sdk/command-auth-native` | Допоміжні засоби native command auth + native session-target | + | `plugin-sdk/approval-delivery-runtime` | Адаптери доставки/можливостей native approval | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply payload для approval exec/plugin | + | `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команди | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору контрактів секретів для поверхонь секретів каналу/плагіна | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізація SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збору секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватних мереж | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору секретних контрактів для секретних поверхонь каналу/плагіна | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, external-content і збору секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом від SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout для запитів | | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/interactive плагінів | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра webhook/internal hook | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для плагінів | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для webhook/internal hook | | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway та патчів статусу каналу | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки на дублікати/конфлікти, навіть коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники approval-capability, auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram та перевірки на дублікати/конфлікти, навіть коли поверхня вбудованого контракту Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби approval exec/plugin, збирачі approval-capability, допоміжні засоби auth/profile, native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, heartbeat, планувальник reply | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для reply | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, значення стану runtime за замовчуванням і допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогу state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби прив’язки маршруту/ключа сесії/облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану runtime та допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних вхідних даних | - | `plugin-sdk/run-command` | Виконавець команд із таймінгом і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витяг канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування чутливих даних | + | `plugin-sdk/request-url` | Витягування рядкових URL із введення, подібного до fetch/request | + | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів інструмента | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляху тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні засоби subsystem logger і редагування чутливих даних | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму Markdown-таблиць | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | - | `plugin-sdk/file-lock` | Допоміжні засоби re-entrant file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковим зберіганням | - | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно-вхідного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового кешу dedupe | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session і reply-dispatch для ACP | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента | | `plugin-sdk/boolean-param` | Гнучкий читач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команді `/models`/провайдера | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native-команд | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів сполучення | + | `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel, статусу та ambient proxy helper | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize для native command | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/heartbeat | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби diagnostic flag і event | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | + | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy та pinned lookup | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імені хоста та SCP-хоста | | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа, а також побудовники медіапейлоадів | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також збирачі медіапейлоадів | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів media understanding і provider-facing експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/markdown/logging, такі як видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech-провайдерів і provider-facing допоміжні засоби директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільні типи speech-провайдерів, допоміжні засоби реєстру, директив і нормалізації | - | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби реєстру | + | `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення видимого для асистента тексту, допоміжні засоби render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і safe-text утиліти | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking для вихідного тексту | + | `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів допоміжні засоби для директив, реєстру та валідації | + | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні засоби реєстру | - | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера і розбір model-ref | - | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера і розбір model-ref | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для користувачів Plugin SDK | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | @@ -266,32 +266,32 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби files/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для допоміжних засобів files/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для memory-adjacent плагінів | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний щодо вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний щодо вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний щодо вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для плагінів, суміжних із пам’яттю | | `plugin-sdk/memory-host-search` | Активний фасад runtime пам’яті для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-host-status` | Нейтральний щодо вендора псевдонім для допоміжних засобів статусу хоста пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - + | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser-плагіна (`browser-support` лишається barrel-файлом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime для вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime для вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів для вбудованого IRC | - | Допоміжні засоби, специфічні для каналу | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні засоби вбудованих каналів | - | Допоміжні засоби, специфічні для auth/плагіна | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів вбудованих функцій/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається barrel-файлом сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого IRC | + | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів для вбудованих каналів | + | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | @@ -302,56 +302,56 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ### Реєстрація можливостей -| Метод | Що реєструє | -| ------------------------------------------------ | ------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний CLI backend inference | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція realtime | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні сесії realtime voice | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| Метод | Що він реєструє | +| ------------------------------------------------ | -------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerCliBackend(...)` | Локальний CLI backend для inference | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Веб-пошук | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що реєструє | -| ------------------------------ | --------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура -| Метод | Що реєструє | -| --------------------------------------------- | -------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP endpoint gateway | -| `api.registerGatewayMethod(name, handler)` | Метод RPC gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | +| Метод | Що він реєструє | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук подій | +| `api.registerHttpRoute(params)` | HTTP endpoint gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фонова служба | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | -Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди лишаються `operator.admin`, навіть якщо плагін намагається призначити -вужчу область дії методу gateway. Для методів, що належать плагіну, віддавайте перевагу -префіксам, специфічним для плагіна. +Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити +вужчу область методу gateway. Для +методів, що належать плагіну, віддавайте перевагу префіксам, специфічним для плагіна. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд на етапі розбору, що використовуються для кореневої довідки CLI, - маршрутизації та лінивої реєстрації CLI плагіна +- `commands`: явні корені команд, які належать registrar +- `descriptors`: дескриптори команд на етапі розбору, які використовуються для довідки кореневого CLI, + маршрутизації та ледачої реєстрації CLI плагіна -Якщо ви хочете, щоб команда плагіна лишалася ліниво завантажуваною у звичайному кореневому шляху CLI, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим +Якщо ви хочете, щоб команда плагіна залишалася ледачо завантажуваною в +звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що експонується цим registrar. ```typescript @@ -364,7 +364,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю", + description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -372,81 +372,87 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, лише якщо вам не потрібна лінива коренева реєстрація CLI. -Цей eager-шлях сумісності все ще підтримується, але він не встановлює -плейсхолдери на основі дескрипторів для лінивого завантаження на етапі розбору. +Використовуйте лише `commands`, якщо вам не потрібна ледача реєстрація кореневого CLI. +Цей сумісний eager-шлях залишається підтримуваним, але він не встановлює +placeholders на основі descriptor для ледачого завантаження на етапі розбору. ### Реєстрація CLI backend -`api.registerCliBackend(...)` дає плагіну змогу володіти конфігурацією за замовчуванням для локального +`api.registerCliBackend(...)` дає змогу плагіну володіти типовою конфігурацією для локального AI CLI backend, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в model ref, як-от `codex-cli/gpt-5`. +- `id` backend стає префіксом провайдера в model ref на кшталт `codex-cli/gpt-5`. - `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. - Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - значень плагіна за замовчуванням перед запуском CLI. + типового значення плагіна перед запуском CLI. - Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття - (наприклад, для нормалізації старих форм прапорців). + (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що реєструє | -| ----------------------------------------- | ----------------------------------- | -| `api.registerContextEngine(id, factory)` | Контекстний рушій (лише один активний одночасно) | -| `api.registerMemoryPromptSection(builder)` | Побудовник розділу prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| Метод | Що він реєструє | +| ------------------------------------------ | ------------------------------------- | +| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один) | +| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану очищення пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери memory embedding +### Адаптери вбудовування пам’яті -| Метод | Що реєструє | -| --------------------------------------------- | ------------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер memory embedding для активного плагіна | +| Метод | Що він реєструє | +| ---------------------------------------------- | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | +- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті. +- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`, + щоб супутні плагіни могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної + структури конкретного плагіна пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` є ексклюзивними для плагінів пам’яті. -- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті реєструвати один - або кілька id embedding-адаптерів (наприклад, `openai`, `gemini` або custom - plugin-defined id). + `registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивних плагінів пам’яті. +- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу зареєструвати один + або більше id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький + id, визначений плагіном). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих id адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| ------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| Метод | Що він робить | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | | `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | -### Семантика рішень hook +### Семантика рішень хука -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропущений `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропущений `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере диспетчеризацію на себе, обробники з нижчим пріоритетом і стандартний шлях диспетчеризації моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропущений `cancel`), а не як перевизначення. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник заявляє про диспетчеризацію, обробники з нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. ### Поля об’єкта API -| Поле | Тип | Опис | -| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | id плагіна | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Специфічна для плагіна конфігурація з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | ID плагіна | +| `api.name` | `string` | Назва для відображення | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | +| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | -## Угода щодо внутрішніх модулів +## Внутрішня угода щодо модулів Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: @@ -455,39 +461,39 @@ my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів runtime-api.ts # Лише внутрішні експорти runtime index.ts # Точка входу плагіна - setup-entry.ts # Легка вхідна точка лише для налаштування (необов’язково) + setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - у production-коді. Виконуйте внутрішні імпорти через `./api.ts` або - `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих плагінів, завантажувані через фасад (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають перевагу -активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime -ще не існує, вони повертаються до визначеного конфігураційного файлу на диску. +Фасадно-завантажувані публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу +активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до визначеного файла конфігурації на диску. -Плагіни провайдерів також можуть відкривати вузький локальний для плагіна barrel контракту, коли -допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. -Поточний вбудований приклад: провайдер Anthropic зберігає свої допоміжні засоби Claude -stream у власному публічному шві `api.ts` / `contract-api.ts` замість -просування логіки Anthropic beta-header і `service_tier` до загального -контракту `plugin-sdk/*`. +Плагіни провайдерів також можуть експонувати вузький локальний barrel-файл контракту плагіна, коли +певний допоміжний засіб навмисно є специфічним для провайдера і ще не належить до +загального підшляху SDK. Поточний вбудований приклад: провайдер Anthropic зберігає свої +допоміжні засоби потоків Claude у власному публічному шві `api.ts` / `contract-api.ts` +замість просування логіки beta-header Anthropic і `service_tier` у загальний +контракт `plugin-sdk/*`. Інші поточні вбудовані приклади: -- `@openclaw/openai-provider`: `api.ts` експортує побудовники провайдерів, - допоміжні засоби моделей за замовчуванням і побудовники realtime-провайдерів -- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник провайдера, а також +- `@openclaw/openai-provider`: `api.ts` експортує збирачі провайдерів, + допоміжні засоби типових моделей і збирачі realtime-провайдерів +- `@openclaw/openrouter-provider`: `api.ts` експортує збирач провайдера, а також допоміжні засоби онбордингу/конфігурації Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, - наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливість, замість жорсткого зв’язування двох плагінів між собою. + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою. ## Пов’язане @@ -497,4 +503,4 @@ stream у власному публічному шві `api.ts` / `contract-api. - [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації - [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint - [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — детальна архітектура та модель можливостей +- [Plugin Internals](/uk/plugins/architecture) — глибока архітектура та модель можливостей