openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-28 00:11:55 +00:00
parent 6a33902e34
commit 90b0171b68
3 changed files with 377 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/uk/cli/skills.md
View File

@ -1,27 +1,27 @@
---
read_when:
- Ви хочете побачити, які Skills доступні й готові до запуску
- Ви хочете шукати, встановлювати або оновлювати Skills із ClawHub
- Ви хочете налагодити відсутні бінарні файли, змінні середовища або конфігурацію для Skills
summary: Довідник CLI для `openclaw skills` (пошук/встановлення/оновлення/список/відомості/перевірка)
- Ви хочете побачити, які Skills доступні та готові до запуску
- Ви хочете знайти, встановити або оновити Skills з ClawHub
- Ви хочете налагодити відсутні бінарні файли/env/конфігурацію для Skills
summary: Довідка CLI для `openclaw skills` (search/install/update/list/info/check)
title: Skills
x-i18n:
generated_at: "2026-04-24T03:16:07Z"
generated_at: "2026-04-28T00:10:36Z"
model: gpt-5.4
provider: openai
source_hash: 31cd7647a15cd5df6cf5a2311e63bb11cc3aabfe8beefda7be57dc76adc509ea
source_hash: 5059bf04c68dabe289d2c376407a52989c970e3d16e7637a2c83f4e24ad6564c
source_path: cli/skills.md
workflow: 15
---
# `openclaw skills`
Переглядайте локальні Skills і встановлюйте/оновлюйте Skills із ClawHub.
Переглядайте локальні Skills та встановлюйте/оновлюйте Skills з ClawHub.
Пов’язано:
Пов’язане:
- Система Skills: [Skills](/uk/tools/skills)
- Конфігурація Skills: [Конфігурація Skills](/uk/tools/skills-config)
- Конфігурація Skills: [Skills config](/uk/tools/skills-config)
- Встановлення з ClawHub: [ClawHub](/uk/tools/clawhub)
## Команди
@ -32,32 +32,50 @@ openclaw skills search --limit 20 --json
openclaw skills install <slug>
openclaw skills install <slug> --version <version>
openclaw skills install <slug> --force
openclaw skills install <slug> --agent <id>
openclaw skills update <slug>
openclaw skills update --all
openclaw skills update --all --agent <id>
openclaw skills list
openclaw skills list --eligible
openclaw skills list --json
openclaw skills list --verbose
openclaw skills list --agent <id>
openclaw skills info <name>
openclaw skills info <name> --json
openclaw skills info <name> --agent <id>
openclaw skills check
openclaw skills check --json
openclaw skills check --agent <id>
```
`search`/`install`/`update` безпосередньо використовують ClawHub і встановлюють у каталог `skills/` активного робочого простору. `list`/`info`/`check` як і раніше переглядають локальні Skills, видимі для поточного робочого простору та конфігурації.
`search`/`install`/`update` напряму використовують ClawHub і встановлюють у активний
каталог робочого простору `skills/`. `list`/`info`/`check` як і раніше перевіряють локальні
Skills, видимі для поточного робочого простору та конфігурації. Команди, що
працюють з робочим простором, визначають цільовий робочий простір через `--agent <id>`,
потім через поточний робочий каталог, якщо він знаходиться всередині налаштованого
робочого простору агента, а потім через агента за замовчуванням.
Ця команда CLI `install` завантажує теки Skills із ClawHub. Встановлення залежностей Skills через Gateway, запущене з онбордингу або налаштувань Skills, натомість використовує окремий шлях запиту `skills.install`.
Ця команда CLI `install` завантажує теки Skills з ClawHub. Встановлення залежностей
Skills через Gateway, які запускаються під час онбордингу або з налаштувань Skills,
замість цього використовують окремий шлях запиту `skills.install`.
Примітки:
- `search [query...]` приймає необов’язковий запит; пропустіть його, щоб переглянути типовий пошуковий канал ClawHub.
- `search [query...]` приймає необов’язковий запит; не вказуйте його, щоб переглянути стандартну
стрічку пошуку ClawHub.
- `search --limit <n>` обмежує кількість повернених результатів.
- `install --force` перезаписує наявну теку Skill у робочому просторі для того самого slug.
- `update --all` оновлює лише відстежувані встановлення ClawHub в активному робочому просторі.
- `list` є типовою дією, якщо не вказано підкоманду.
- `list`, `info` і `check` записують свій сформований вивід у stdout. Із `--json` це означає, що машиночитний вміст залишається в stdout для конвеєрів і скриптів.
- `install --force` перезаписує наявну теку Skills робочого простору для того самого
slug.
- `--agent <id>` націлюється на один налаштований робочий простір агента та перевизначає
визначення за поточним робочим каталогом.
- `update --all` оновлює лише відстежувані встановлення з ClawHub в активному робочому просторі.
- `list` є дією за замовчуванням, якщо не вказано підкоманду.
- `list`, `info` і `check` записують свій відформатований вивід у stdout. З
`--json` це означає, що машинозчитувані дані залишаються у stdout для каналів
і скриптів.
## Пов’язано
## Пов’язане
- [Довідник CLI](/uk/cli)
- [Довідка CLI](/uk/cli)
- [Skills](/uk/tools/skills)

234
docs/uk/plugins/hooks.md
View File

@ -2,21 +2,21 @@
read_when:
- Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу
- Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin
- Ви обираєте між внутрішніми хуками та хуками plugin
- 'Ви вирішуєте, що вибрати: внутрішні хуки чи хуки Plugin'
summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway'
title: Хуки Plugin
title: хуки Plugin
x-i18n:
generated_at: "2026-04-27T22:37:53Z"
generated_at: "2026-04-28T00:10:39Z"
model: gpt-5.4
provider: openai
source_hash: 0aae1c2321491ed0eb82b6306be61cd7e4bffccf8e22d1455267110fdf4fc62b
source_hash: 2bdc52ada8f8949f24b7930ee1daac254477ef678396ea61102775173f68e0d5
source_path: plugins/hooks.md
workflow: 15
---
Хуки Plugin — це внутрішньопроцесні точки розширення для plugin OpenClaw. Використовуйте їх,
Хуки Plugin — це точки розширення в процесі виконання для plugin OpenClaw. Використовуйте їх,
коли plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень,
життєвий цикл сесії, маршрутизацію сабагентів, встановлення або запуск Gateway.
життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway.
Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий
скрипт `HOOK.md`, встановлений оператором, для подій команд і Gateway, таких як
@ -56,65 +56,67 @@ export default definePluginEntry({
});
```
Обробники хуків виконуються послідовно у порядку спадання `priority`. Хуки з однаковим пріоритетом
зберігають порядок реєстрації.
Обробники хуків виконуються послідовно в порядку спадання `priority`. Хуки з
однаковим пріоритетом зберігають порядок реєстрації.
Кожен хук отримує `event.context.pluginConfig` — розв’язану конфігурацію для
plugin, який зареєстрував цей обробник. Використовуйте її для рішень у хуках, яким
потрібні поточні параметри plugin; OpenClaw інжектує її для кожного обробника, не змінюючи
спільний об’єкт події, який бачать інші plugins.
Кожен хук отримує `event.context.pluginConfig` — обчислену конфігурацію для
plugin, який зареєстрував цей обробник. Використовуйте її для рішень у хуках,
яким потрібні поточні параметри plugin; OpenClaw додає її для кожного
обробника без змінювання спільного об’єкта події, який бачать інші plugins.
## Каталог хуків
Хуки згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають
результат рішення (block, cancel, override або require approval); усі інші призначені
лише для спостереження.
Хуки згруповані за поверхнею, яку вони розширюють. Назви **жирним** приймають
результат рішення (блокування, скасування, перевизначення або вимога схвалення);
усі інші призначені лише для спостереження.
**Хід агента**
- `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії
- `before_prompt_build` — додати динамічний контекст або текст системного промпту перед викликом моделі
- `before_agent_start` — сумісна комбінована фаза; натомість віддавайте перевагу двом хукам вище
- **`before_agent_reply`** — завершити хід моделі достроково синтетичною відповіддю або тишею
- `agent_turn_prepare` — спожити поставлені в чергу ін’єкції ходу plugin і додати контекст того самого ходу до хуків промпта
- `before_prompt_build` — додати динамічний контекст або текст системного промпта до виклику моделі
- `before_agent_start` — комбінована фаза лише для сумісності; натомість віддавайте перевагу двом хукам вище
- **`before_agent_reply`** — перервати хід моделі синтетичною відповіддю або безшумно
- **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі
- `agent_end` — спостерігати за фінальними повідомленнями, станом успіху та тривалістю запуску
- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску
- `heartbeat_prompt_contribution` — додати контекст лише для Heartbeat для фонових моніторів і plugin життєвого циклу
**Спостереження за розмовою**
- `model_call_started` / `model_call_ended` — спостерігати за очищеними метаданими виклику провайдера/моделі, часом, результатом і обмеженими хешами request id без вмісту промпту або відповіді
- `llm_input` — спостерігати за входом провайдера (системний промпт, промпт, історія)
- `llm_output` — спостерігати за виходом провайдера
- `model_call_started` / `model_call_ended` — спостерігати очищені метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту промпта або відповіді
- `llm_input` — спостерігати вхід провайдера (системний промпт, промпт, історія)
- `llm_output` — спостерігати вихід провайдера
**Інструменти**
- **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення
- `after_tool_call` — спостерігати за результатами інструментів, помилками та тривалістю
- **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента
- `after_tool_call` — спостерігати результати інструмента, помилки та тривалість
- **`tool_result_persist`** — переписати повідомлення помічника, створене з результату інструмента
- **`before_message_write`** — перевірити або заблокувати запис повідомлення в процесі (рідко)
**Повідомлення та доставка**
- **`inbound_claim`** — перехопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді)
- `message_received` — спостерігати за вхідним вмістом, відправником, потоком і метаданими
- `message_received` — спостерігати вхідний вміст, відправника, гілку та метадані
- **`message_sending`** — переписати вихідний вміст або скасувати доставку
- `message_sent` — спостерігати за успіхом або невдачею вихідної доставки
- **`before_dispatch`** — перевірити або переписати вихідний dispatch перед передачею каналу
- `message_sent` — спостерігати успіх або збій вихідної доставки
- **`before_dispatch`** — перевірити або переписати вихідне dispatch до передавання каналу
- **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді
**Сесії та Compaction**
- `session_start` / `session_end` — відстежувати межі життєвого циклу сесії
- `before_compaction` / `after_compaction` — спостерігати за циклами Compaction або анотувати їх
- `before_reset` — спостерігати за подіями скидання сесії (`/reset`, програмні скидання)
- `before_compaction` / `after_compaction` — спостерігати або анотувати цикли Compaction
- `before_reset` — спостерігати події скидання сесії (`/reset`, програмні скидання)
**Сабагенти**
**Субагенти**
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію сабагентів і доставку завершення
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію субагентів і доставку після завершення
**Життєвий цикл**
- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси, якими володіє plugin, разом із Gateway
- **`before_install`** — перевіряти сканування встановлення skill або plugin та за потреби блокувати
- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси plugin разом із Gateway
- **`before_install`** — перевіряти сканування встановлення skill або plugin і за потреби блокувати
## Політика викликів інструментів
@ -125,7 +127,7 @@ plugin, який зареєстрував цей обробник. Викори
- необов’язковий `event.runId`
- необов’язковий `event.toolCallId`
- поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
`ctx.runId`, `ctx.jobId` (встановлюється для запусків, ініційованих Cron), і діагностичний `ctx.trace`
`ctx.runId`, `ctx.jobId` (встановлюється для запусків, керованих cron), і діагностичний `ctx.trace`
Він може повертати:
@ -151,64 +153,58 @@ type BeforeToolCallResult = {
Правила:
- `block: true` є термінальним і пропускає обробники з нижчим пріоритетом.
- `block: false` вважається відсутністю рішення.
- `block: false` розглядається як відсутність рішення.
- `params` переписує параметри інструмента для виконання.
- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin.
Команда `/approve` може схвалювати як exec, так і схвалення plugin.
- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом
запросив схвалення.
- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin. Команда `/approve` може схвалювати як exec, так і схвалення plugin.
- `block: true` із нижчим пріоритетом усе одно може заблокувати після того, як хук із вищим пріоритетом запросив схвалення.
- `onResolution` отримує підсумкове рішення щодо схвалення — `allow-once`,
`allow-always`, `deny`, `timeout` або `cancelled`.
### Збереження результатів інструментів
Вбудовані plugins, яким потрібна політика рівня хоста, можуть реєструвати довірені політики інструментів через `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних хуків `before_tool_call` і до рішень зовнішніх plugin. Використовуйте їх лише для довірених хостом бар’єрів, таких як політика робочого простору, контроль бюджету або безпека зарезервованих робочих процесів. Зовнішні plugins мають використовувати звичайні хуки `before_tool_call`.
Результати інструментів можуть містити структуровані `details` для рендерингу в UI, діагностики,
маршрутизації медіа або метаданих, якими володіє plugin. Сприймайте `details` як метадані
середовища виконання, а не як вміст промпту:
### Збереження результатів інструмента
- OpenClaw видаляє `toolResult.details` перед повторним відтворенням у провайдері та входом Compaction,
щоб метадані не ставали контекстом моделі.
- Збережені записи сесії зберігають лише обмежені `details`. Надто великі details
замінюються компактним підсумком і `persistedDetailsTruncated: true`.
- `tool_result_persist` і `before_message_write` виконуються перед фінальним
обмеженням збереження. Хуки все одно мають зберігати повернуті `details` невеликими й уникати
розміщення важливого для промпту тексту лише в `details`; видимий для моделі вихід інструмента
слід поміщати в `content`.
Результати інструмента можуть містити структуровані `details` для рендерингу в UI, діагностики,
маршрутизації медіа або метаданих, що належать plugin. Розглядайте `details` як
метадані часу виконання, а не як вміст промпта:
## Хуки промпту та моделі
- OpenClaw видаляє `toolResult.details` перед повторним відтворенням провайдером і входом Compaction, щоб метадані не ставали контекстом моделі.
- Постійно збережені записи сесії містять лише обмежені `details`. Завеликі details замінюються компактним підсумком і `persistedDetailsTruncated: true`.
- `tool_result_persist` і `before_message_write` виконуються до фінального обмеження на постійне збереження. Хуки все одно мають тримати повернуті `details` малими й уникати розміщення тексту, релевантного для промпта, лише в `details`; видимий для моделі вихід інструмента слід поміщати в `content`.
## Хуки промпта та моделі
Для нових plugins використовуйте хуки, специфічні для фази:
- `before_model_resolve`: отримує лише поточний промпт і метадані вкладень. Поверніть `providerOverride` або `modelOverride`.
- `before_prompt_build`: отримує поточний промпт і повідомлення сесії.
Поверніть `prependContext`, `systemPrompt`, `prependSystemContext` або
`appendSystemContext`.
- `agent_turn_prepare`: отримує поточний промпт, підготовлені повідомлення сесії та будь-які ін’єкції рівно-один-раз, зняті з черги для цієї сесії. Поверніть `prependContext` або `appendContext`.
- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. Поверніть `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`.
- `heartbeat_prompt_contribution`: виконується лише для ходів Heartbeat і повертає `prependContext` або `appendContext`. Призначений для фонових моніторів, яким потрібно підсумовувати поточний стан без зміни ходів, ініційованих користувачем.
`before_agent_start` залишається для сумісності. Надавайте перевагу явним хукам вище,
`before_agent_start` зберігається для сумісності. Віддавайте перевагу явним хукам вище,
щоб ваш plugin не залежав від застарілої комбінованої фази.
`before_agent_start` і `agent_end` включають `event.runId`, коли OpenClaw може
ідентифікувати активний запуск. Це саме значення також доступне в `ctx.runId`.
Запуски, ініційовані Cron, також мають `ctx.jobId` (ідентифікатор вихідного завдання cron), щоб
хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретного запланованого
завдання.
`before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може
визначити активний запуск. Те саме значення також доступне в `ctx.runId`.
Запуски, керовані Cron, також надають `ctx.jobId` (ідентифікатор вихідної Cron-задачі), щоб
хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретної
запланованої задачі.
Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера,
яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів
або request id провайдера. Ці хуки містять стабільні метадані, такі як
Використовуйте `model_call_started` і `model_call_ended` для телеметрії
викликів провайдера, яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів або request ID провайдера. Ці хуки містять стабільні метадані, такі як
`runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, фінальні
`durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може вивести
обмежений хеш request id провайдера.
`durationMs`/`outcome` та `upstreamRequestIdHash`, коли OpenClaw може вивести
обмежений хеш request-id провайдера.
`before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну
фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не
фінальну відповідь помічника. Це не шлях скасування `/stop`, і він не
виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб
попросити harness зробити ще один прохід моделі перед фіналізацією, `{ action:
"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат,
щоб продовжити. Нативні хуки Codex `Stop` ретранслюються в цей хук як рішення OpenClaw
попросити harness виконати ще один прохід моделі до фіналізації, `{ action:
"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, щоб продовжити.
Власні хуки `Stop` у Codex передаються в цей хук як рішення OpenClaw
`before_agent_finalize`.
Зовнішні plugins, не включені до складу, яким потрібні `llm_input`, `llm_output`,
Невбудовані plugins, яким потрібні `llm_input`, `llm_output`,
`before_agent_finalize` або `agent_end`, мають встановити:
```json
@ -225,66 +221,90 @@ type BeforeToolCallResult = {
}
```
Хуки, що змінюють промпт, можна вимкнути для кожного plugin через
`plugins.entries.<id>.hooks.allowPromptInjection=false`.
Хуки, що змінюють промпт, і стійкі ін’єкції наступного ходу можна вимкнути для кожного plugin
через `plugins.entries.<id>.hooks.allowPromptInjection=false`.
### Розширення сесії та ін’єкції наступного ходу
Workflow plugins можуть зберігати невеликий JSON-сумісний стан сесії за допомогою
`api.registerSessionExtension(...)` і оновлювати його через метод Gateway
`sessions.pluginPatch`. Рядки сесії проєктують зареєстрований стан розширення через
`pluginExtensions`, що дозволяє Control UI та іншим клієнтам відображати
стан, який належить plugin, без вивчення внутрішньої реалізації plugin.
Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin потрібен стійкий контекст, який
має потрапити до наступного ходу моделі рівно один раз. OpenClaw знімає поставлені в чергу ін’єкції до
хуків промпта, відкидає прострочені ін’єкції та усуває дублікати за `idempotencyKey`
для кожного plugin. Це правильна точка інтеграції для відновлення після схвалення,
підсумків політик, змін від фонового монітора та продовжень команд, які
мають бути видимі моделі на наступному ході, але не повинні ставати постійним
текстом системного промпта.
Семантика очищення є частиною контракту. Зворотні виклики очищення розширень сесії та
очищення життєвого циклу часу виконання отримують `reset`, `delete`, `disable` або
`restart`. Хост видаляє постійний стан розширення сесії плагіна-власника та
очікувані ін’єкції наступного ходу для `reset`/`delete`/`disable`; `restart` зберігає
стійкий стан сесії, а зворотні виклики очищення дають plugins змогу звільняти
задачі планувальника, контекст виконання та інші позасмугові ресурси для старого
покоління часу виконання.
## Хуки повідомлень
Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки:
- `message_received`: спостерігати за вхідним вмістом, відправником, `threadId`, `messageId`,
`senderId`, необов’язковою кореляцією запуску/сесії та метаданими.
- `message_received`: спостерігати вхідний вміст, відправника, `threadId`, `messageId`,
`senderId`, необов’язкову кореляцію запуску/сесії та метадані.
- `message_sending`: переписати `content` або повернути `{ cancel: true }`.
- `message_sent`: спостерігати за остаточним успіхом або невдачею.
- `message_sent`: спостерігати фінальний успіх або збій.
Для аудіо-відповідей TTS без тексту `content` може містити приховану озвучену транскрипцію,
навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього
`content` оновлює лише транскрипцію, видиму для хука; воно не рендериться як
підпис до медіа.
Для відповідей TTS лише з аудіо `content` може містити приховану транскрипцію
озвученого тексту, навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього
`content` оновлює лише видиму для хука транскрипцію; воно не відображається як
підпис медіа.
Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні:
`ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`,
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Надавайте перевагу
цим полям першого класу, а не читанню застарілих метаданих.
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу
цим полям першого класу, перш ніж звертатися до застарілих метаданих.
Надавайте перевагу типізованим полям `threadId` і `replyToId`, а не використанню
метаданих, специфічних для каналу.
Віддавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати
метадані, специфічні для каналу.
Правила рішень:
- `message_sending` з `cancel: true` є термінальним.
- `message_sending` з `cancel: false` вважається відсутністю рішення.
- `message_sending` з `cancel: false` розглядається як відсутність рішення.
- Переписаний `content` передається далі хукам із нижчим пріоритетом, якщо пізніший хук
не скасує доставку.
## Хуки встановлення
`before_install` виконується після вбудованого сканування для встановлень skill і plugin.
Поверніть додаткові findings або `{ block: true, blockReason }`, щоб зупинити
Поверніть додаткові результати або `{ block: true, blockReason }`, щоб зупинити
встановлення.
`block: true` є термінальним. `block: false` вважається відсутністю рішення.
`block: true` є термінальним. `block: false` розглядається як відсутність рішення.
## Життєвий цикл Gateway
Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway.
Контекст надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для
перевірки та оновлення Cron. Використовуйте `gateway_stop`, щоб очищати довготривалі
Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст
надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для
перевірки та оновлення cron. Використовуйте `gateway_stop`, щоб очищати довготривалі
ресурси.
Не покладайтеся на внутрішній хук `gateway:startup` для сервісів середовища виконання,
якими володіє plugin.
Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання,
що належать plugin.
## Майбутні застарівання
Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Виконайте
Кілька поверхонь, суміжних із хуками, застаріли, але все ще підтримуються. Виконайте
міграцію до наступного мажорного релізу:
- **Текстові plaintext-конверти каналів** в обробниках `inbound_claim` і `message_received`.
- **Незашифровані конверти каналу** в обробниках `inbound_claim` і `message_received`.
Читайте `BodyForAgent` і структуровані блоки контексту користувача
замість розбору плаского тексту конверта. Див.
[Plaintext channel envelopes → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** залишається для сумісності. Нові plugins мають використовувати
замість парсингу плоского тексту конверта. Див.
[Незашифровані конверти каналу → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** зберігається для сумісності. Нові plugins мають використовувати
`before_model_resolve` і `before_prompt_build` замість комбінованої
фази.
- **`onResolution` у `before_tool_call`** тепер використовує типізоване
@ -292,15 +312,15 @@ type BeforeToolCallResult = {
`timeout` / `cancelled`) замість довільного `string`.
Повний список — реєстрація можливостей пам’яті, профіль thinking провайдера,
зовнішні провайдери auth, типи виявлення провайдерів, аксесори TaskFlow середовища виконання
та перейменування `command-auth` → `command-status` — див. у
[Plugin SDK migration → Active deprecations](/uk/plugins/sdk-migration#active-deprecations).
зовнішні провайдери автентифікації, типи виявлення провайдерів, аксесори часу виконання задач
і перейменування `command-auth` → `command-status` — див. у
[Міграція Plugin SDK → Активні застарівання](/uk/plugins/sdk-migration#active-deprecations).
## Пов’язані матеріали
## Пов’язане
- [Plugin SDK migration](/uk/plugins/sdk-migration) — активні застарівання та графік видалення
- [Building plugins](/uk/plugins/building-plugins)
- [Plugin SDK overview](/uk/plugins/sdk-overview)
- [Plugin entry points](/uk/plugins/sdk-entrypoints)
- [Internal hooks](/uk/automation/hooks)
- [Plugin architecture internals](/uk/plugins/architecture-internals)
- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та графік видалення
- [Створення plugins](/uk/plugins/building-plugins)
- [Огляд Plugin SDK](/uk/plugins/sdk-overview)
- [Точки входу Plugin](/uk/plugins/sdk-entrypoints)
- [Внутрішні хуки](/uk/automation/hooks)
- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals)

381
docs/uk/plugins/sdk-overview.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Вам потрібно знати, з якого підшляху SDK імпортувати
- Потрібно знати, з якого підшляху SDK імпортувати
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
- Ви шукаєте конкретний експорт SDK
sidebarTitle: SDK overview
summary: Import map, довідник API реєстрації та архітектура SDK
summary: Карта імпорту, довідник з API реєстрації та архітектура SDK
title: Огляд Plugin SDK
x-i18n:
generated_at: "2026-04-27T11:01:36Z"
generated_at: "2026-04-28T00:10:37Z"
model: gpt-5.4
provider: openai
source_hash: 205c57492fd2c90c01a87bae34716d6abcf420c7bdc2f51bd3042e52a3872ec6
source_hash: f9b00b189c2a5e632a1c7e614a3e9371dcc3114d3582d795e3c88fb5d5a0f13a
source_path: plugins/sdk-overview.md
workflow: 15
---
Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка —
Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка —
довідник про **що імпортувати** і **що можна реєструвати**.
<Tip>
@ -27,7 +27,7 @@ Plugin SDK — це типізований контракт між плагін
- Плагін інструмента або хука життєвого циклу? Див. [Хуки плагінів](/uk/plugins/hooks).
</Tip>
## Угода щодо імпорту
## Правило імпорту
Завжди імпортуйте з конкретного підшляху:
@ -38,37 +38,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`.
Для конфігурації каналу публікуйте JSON Schema, якою володіє канал, через
Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через
`openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema`
призначений для спільних примітивів схем і узагальненого builder. Застарілі
експорти схем вбудованих каналів знаходяться в `plugin-sdk/channel-config-schema-legacy`
лише для сумісності зі вбудованими компонентами; це не шаблон для нових плагінів.
призначений для спільних примітивів схем і універсального збирача. Застарілі
експорти схем вбудованих каналів розміщено в
`plugin-sdk/channel-config-schema-legacy` лише для сумісності з вбудованими
рішеннями; це не шаблон для нових плагінів.
<Warning>
Не імпортуйте branded convenience seams для провайдерів або каналів (наприклад
Не імпортуйте зручні seam-інтерфейси, позначені як provider або channel (наприклад
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Вбудовані плагіни композують узагальнені підшляхи SDK усередині власних barrel-файлів
`api.ts` / `runtime-api.ts`; споживачі core мають або використовувати ці локальні
barrel-файли плагіна, або додавати вузький узагальнений контракт SDK, коли потреба
Вбудовані плагіни поєднують універсальні підшляхи SDK усередині власних barrel-файлів
`api.ts` / `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні
barrel-файли плагіна, або додати вузький універсальний контракт SDK, якщо потреба
справді є міжканальною.
Невеликий набір helper seams вбудованих плагінів (`plugin-sdk/feishu`,
`plugin-sdk/zalo`, `plugin-sdk/matrix*` тощо) усе ще присутній у
згенерованій мапі експортів. Вони існують лише для підтримки вбудованих плагінів і
Невеликий набір допоміжних seam-інтерфейсів для вбудованих плагінів (`plugin-sdk/feishu`,
`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще присутній у
згенерованій карті експортів. Вони існують лише для супроводу вбудованих плагінів і
не рекомендуються як шляхи імпорту для нових сторонніх плагінів.
</Warning>
## Довідник підшляхів
Plugin SDK доступний як набір вузьких підшляхів, згрупованих за областями (entry
плагіна, канал, провайдер, auth, runtime, capability, memory і зарезервовані
хелпери вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див. у
[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
Plugin SDK надається як набір вузьких підшляхів, згрупованих за напрямами (entry
плагіна, channel, provider, auth, runtime, capability, memory і зарезервовані
допоміжні засоби для вбудованих плагінів). Повний каталог — згрупований і з
посиланнями — див. у [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
@ -79,75 +80,119 @@ Plugin SDK доступний як набір вузьких підшляхів,
### Реєстрація можливостей
| Метод | Що реєструє |
| ----------------------------------------------- | ------------------------------------ |
| `api.registerProvider(...)` | Текстове inferencing (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
| `api.registerCliBackend(...)` | Локальний backend inferencing CLI |
| `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.registerProvider(...)` | Текстову інференцію (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
| `api.registerCliBackend(...)` | Локальний backend інференції CLI |
| `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.registerTool(tool, opts?)`| Інструмент агента (обов’язковий або `{ optional: true }`) |
| `api.registerCommand(def)` | Власна команда (обходить LLM) |
| Метод | Що він реєструє |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
| `api.registerCommand(def)` | Користувацьку команду (обходить LLM) |
Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка
підказка маршрутизації, якою володіє команда. Тримайте цей текст про саму команду;
не додавайте специфічну для провайдера або плагіна політику до builder-ів промптів core.
Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна
коротка підказка маршрутизації, що належить команді. Робіть цей текст саме про
команду; не додавайте специфічну для провайдера чи плагіна політику до
збирачів prompt у ядрі.
### Інфраструктура
| Метод | Що реєструє |
| --------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Хук події |
| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerGatewayDiscoveryService(service)`| Локальний advertiser виявлення Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
| `api.registerService(service)` | Фонова служба |
| `api.registerInteractiveHandler(registration)`| Інтерактивний handler |
| `api.registerAgentToolResultMiddleware(...)` | Middleware результату інструмента під час виконання |
| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція промпту поруч із пам’яттю |
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
| Метод | Що він реєструє |
| ---------------------------------------------- | -------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Хук події |
| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerGatewayDiscoveryService(service)` | Сервіс оголошення локального виявлення Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманду CLI |
| `api.registerService(service)` | Фоновий сервіс |
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
| `api.registerAgentToolResultMiddleware(...)` | Проміжний обробник результатів інструментів runtime |
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory |
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус для пошуку/читання memory |
### Хуки хоста для workflow-плагінів
Хуки хоста — це seam-інтерфейси SDK для плагінів, яким потрібно брати участь у
життєвому циклі хоста, а не лише додавати provider, channel або tool. Це
універсальні контракти; їх може використовувати Plan Mode, але так само ними
можуть користуватися workflow затвердження, шлюзи політик робочого простору,
фонові монітори, майстри налаштування та UI-плагіни-компаньйони.
| Метод | Контракт, яким він володіє |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | Стан сесії, що належить плагіну, сумісний із JSON і проєктується через сесії Gateway |
| `api.enqueueNextTurnInjection(...)` | Надійний контекст рівно-один-раз, що вбудовується в наступний хід агента для однієї сесії |
| `api.registerTrustedToolPolicy(...)` | Політика інструментів trusted/bundled до плагіна, яка може блокувати або переписувати параметри інструментів |
| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента |
| `api.registerCommand(...)` | Обмежені команди плагіна; результати команд можуть встановлювати `continueAgent: true` |
| `api.registerControlUiDescriptor(...)` | Дескриптори внеску в Control UI для поверхонь сесій, інструментів, запусків або налаштувань |
| `api.registerRuntimeLifecycle(...)` | Колбеки очищення для ресурсів runtime, що належать плагіну, на шляхах reset/delete/reload |
| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна на рівні запуску, що очищується на завершальному етапі життєвого циклу запуску |
| `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сесій, що належать плагіну, з детермінованим очищенням |
Ці контракти навмисно розділяють повноваження:
- Зовнішні плагіни можуть володіти розширеннями сесій, дескрипторами UI, командами,
метаданими інструментів, ін’єкціями в наступний хід і звичайними хуками.
- Політики trusted інструментів виконуються до звичайних хуків `before_tool_call` і
доступні лише для bundled, оскільки вони беруть участь у політиці безпеки хоста.
- Володіння зарезервованими командами доступне лише для bundled. Зовнішнім плагінам
слід використовувати власні назви команд або псевдоніми.
- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
полями prompt із застарілого `before_agent_start` і
`enqueueNextTurnInjection`.
Приклади споживачів, не пов’язаних із Plan:
| Архетип плагіна | Використовувані хуки |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow затвердження | Розширення сесії, продовження команди, ін’єкція в наступний хід, дескриптор UI |
| Шлюз політик бюджету/робочого простору | Trusted tool policy, metadata інструментів, проєкція сесії |
| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок у Heartbeat prompt, дескриптор UI |
| Майстер налаштування або онбордингу | Розширення сесії, обмежені команди, дескриптор Control UI |
<Note>
Зарезервовані адміністраторські простори імен core (`config.*`, `exec.approvals.*`, `wizard.*`,
Зарезервовані простори назв адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити
вужчий scope методу Gateway. Для методів, якими володіє плагін, віддавайте перевагу
префіксам, специфічним для плагіна.
вужчу область видимості методу gateway. Для методів, що належать плагіну,
віддавайте перевагу префіксам, специфічним для плагіна.
</Note>
<Accordion title="Коли використовувати middleware результату інструмента">
<Accordion title="Коли використовувати проміжний обробник результатів інструментів">
Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
їм потрібно переписати результат інструмента після виконання і до того, як runtime
поверне цей результат назад у модель. Це надійний runtime-neutral seam для
асинхронних reducer-ів виходу, таких як tokenjuice.
поверне цей результат назад у модель. Це trusted і runtime-нейтральний
seam-інтерфейс для асинхронних редукторів виводу, таких як tokenjuice.
Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного
цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни
не можуть реєструвати це middleware; для роботи, якій не потрібен таймінг
результату інструмента до моделі, використовуйте звичайні хуки плагінів OpenClaw. Старий
шлях реєстрації factory вбудованих extension лише для Pi було видалено.
Вбудовані плагіни повинні оголошувати `contracts.agentToolResultMiddleware` для
кожного цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни
не можуть реєструвати цей middleware; для роботи, якій не потрібен таймінг
результатів інструментів до моделі, використовуйте звичайні хуки плагінів OpenClaw. Старий
шлях реєстрації фабрики вбудованих розширень лише для Pi було вилучено.
</Accordion>
### Реєстрація виявлення Gateway
`api.registerGatewayDiscoveryService(...)` дає змогу плагіну рекламувати активний
Gateway через локальний транспорт виявлення, такий як mDNS/Bonjour. OpenClaw викликає службу
під час запуску Gateway, коли локальне виявлення ввімкнене, передає поточні
порти Gateway і не секретні TXT-підказки, а також викликає повернений
handler `stop` під час вимкнення Gateway.
`api.registerGatewayDiscoveryService(...)` дозволяє плагіну оголошувати активний
Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає
сервіс під час запуску Gateway, коли ввімкнено локальне виявлення, передає
поточні порти Gateway і не секретні підказки даних TXT, а також викликає
повернений обробник `stop` під час зупинки Gateway.
```typescript
api.registerGatewayDiscoveryService({
@ -163,20 +208,21 @@ api.registerGatewayDiscoveryService({
});
```
Плагіни виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або
автентифікацію. Виявлення — це підказка маршрутизації; довірою й далі керують auth Gateway і pinning TLS.
Плагіни виявлення Gateway не повинні трактувати оголошені значення TXT як
секрети або автентифікацію. Виявлення — це підказка маршрутизації; довірою, як і
раніше, керують автентифікація Gateway та TLS pinning.
### Метадані реєстрації CLI
`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
- `commands`: явні корені команд, якими володіє registrar
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для довідки кореневого CLI,
- `commands`: явні корені команд, якими володіє реєстратор
- `descriptors`: дескриптори команд на етапі парсингу, які використовуються для довідки кореневого CLI,
маршрутизації та лінивої реєстрації CLI плагіна
Якщо ви хочете, щоб команда плагіна лишалася ліниво завантажуваною в нормальному шляху кореневого CLI,
надайте `descriptors`, що покривають кожен корінь команди верхнього рівня, який відкриває цей
registrar.
Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною в
звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен
корінь команди верхнього рівня, що експонується цим реєстратором.
```typescript
api.registerCli(
@ -188,7 +234,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю",
description: "Manage Matrix accounts, verification, devices, and profile state",
hasSubcommands: true,
},
],
@ -196,93 +242,94 @@ api.registerCli(
);
```
Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI.
Цей eager-сумісний шлях усе ще підтримується, але він не встановлює
плейсхолдери на основі дескрипторів для лінивого завантаження на етапі парсингу.
Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація
кореневого CLI. Цей сумісний eager-шлях усе ще підтримується, але він не
встановлює заповнювачі на основі descriptors для лінивого завантаження на етапі
парсингу.
### Реєстрація backend CLI
`api.registerCliBackend(...)` дає змогу плагіну володіти конфігурацією за замовчуванням для локального
AI backend CLI, такого як `codex-cli`.
`api.registerCliBackend(...)` дозволяє плагіну володіти конфігурацією за
замовчуванням для локального backend CLI ШІ, такого як `codex-cli`.
- `id` backend стає префіксом провайдера в посиланнях на моделі, наприклад `codex-cli/gpt-5`.
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
значень плагіна за замовчуванням перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття
(наприклад нормалізації старих форм прапорців).
- `id` backend стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`.
- `config` backend використовує ту саму структуру, що й `agents.defaults.cliBackends.<id>`.
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
значення за замовчуванням плагіна перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття
(наприклад, для нормалізації старих форм прапорців).
### Ексклюзивні слоти
| Метод | Що реєструє |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати адитивні промпти. |
| `api.registerMemoryCapability(capability)`| Єдину можливість пам’яті |
| `api.registerMemoryPromptSection(builder)`| Builder секції промпту пам’яті |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті |
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
| Метод | Що він реєструє |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine (одночасно активним може бути лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення prompt. |
| `api.registerMemoryCapability(capability)` | Уніфіковану можливість memory |
| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt для memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory |
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory |
### Адаптери embedding пам’яті
### Адаптери embedding для memory
| Метод | Що реєструє |
| ---------------------------------------------- | -------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна |
| Метод | Що він реєструє |
| ---------------------------------------------- | ----------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного плагіна |
- `registerMemoryCapability` — рекомендований API ексклюзивного плагіна пам’яті.
- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
щоб супровідні плагіни могли споживати експортовані артефакти пам’яті через
`openclaw/plugin-sdk/memory-host-core` замість проникнення в приватну розкладку
конкретного плагіна пам’яті.
- `registerMemoryCapability` — бажаний API ексклюзивного memory-плагіна.
- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`,
щоб плагіни-компаньйони могли споживати експортовані артефакти memory через
`openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури
конкретного memory-плагіна.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
`registerMemoryRuntime` — застаріло-сумісні API ексклюзивного плагіна пам’яті.
- `registerMemoryEmbeddingProvider` дає змогу активному плагіну пам’яті зареєструвати один
або кілька ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або
власний ідентифікатор, визначений плагіном).
`registerMemoryRuntime` — це сумісні з legacy API ексклюзивного memory-плагіна.
- `registerMemoryEmbeddingProvider` дозволяє активному memory-плагіну реєструвати один
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або
власний id, визначений плагіном).
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
`agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих
ідентифікаторів адаптерів.
`agents.defaults.memorySearch.fallback`, резолвиться відносно цих зареєстрованих
id адаптерів.
### Події та життєвий цикл
| Метод | Що робить |
| ------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
| `api.onConversationBindingResolved(handler)`| Колбек прив’язки розмови |
| Метод | Що він робить |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови |
Див. [Хуки плагінів](/uk/plugins/hooks), щоб переглянути приклади, поширені назви хуків і
семантику guard.
Приклади, поширені назви хуків і семантику guard див. у
[Хуки плагінів](/uk/plugins/hooks).
### Семантика рішень у хуках
### Семантика рішень хуків
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються.
- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються.
- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере dispatch на себе, handler-и нижчого пріоритету та стандартний шлях dispatch моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перебирає на себе dispatch, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються.
- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення.
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. `metadata` залишайте для специфічних для каналу доповнень.
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для специфічних для каналу додаткових даних.
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для каналу `metadata`.
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`.
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість опори на внутрішні хуки `gateway:startup`.
### Поля об’єкта API
| Поле | Тип | Опис |
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Ідентифікатор плагіна |
| `api.name` | `string` | Назва для відображення |
| `api.version` | `string?` | Версія плагіна (необов’язково) |
| `api.description` | `string?` | Опис плагіна (необов’язково) |
| `api.source` | `string` | Шлях до джерела плагіна |
| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) |
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) |
| `api.pluginConfig` | `Record<string, unknown>` | Специфічна для плагіна конфігурація з `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Хелпери runtime](/uk/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Логер з областю видимості (`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<string, unknown>` | Специфічна для плагіна конфігурація з `plugins.entries.<id>.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-файли для внутрішніх імпортів:
@ -296,41 +343,41 @@ my-plugin/
<Warning>
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
з production-коду. Для внутрішніх імпортів використовуйте `./api.ts` або
`./runtime-api.ts`. Шлях SDK — лише зовнішній контракт.
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
</Warning>
Публічні поверхні вбудованих плагінів, завантажені через facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), надають перевагу
активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime
ще не існує, вони переходять у резервний режим до визначеного файла конфігурації на диску.
Публічні поверхні вбудованих плагінів, завантажувані через facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу
активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime
ще не існує, вони повертаються до резолвленого файлу конфігурації на диску.
Плагіни провайдерів можуть відкривати вузький локальний контрактний barrel плагіна, коли
helper навмисно є специфічним для провайдера і ще не належить до узагальненого підшляху SDK.
Приклади вбудованих плагінів:
Плагіни провайдерів можуть експонувати вузький локальний barrel-контракт плагіна, коли
певний helper навмисно є специфічним для провайдера і поки що не належить до
універсального підшляху SDK. Приклади вбудованих рішень:
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для helper-ів
beta-header Claude і `service_tier` stream.
- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдера,
helper-и моделей за замовчуванням і builder-и провайдерів realtime.
- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера
разом із helper-ами онбордингу/конфігурації.
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для helper-функцій
beta-header Claude і потоку `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдерів,
helper-и моделей за замовчуванням і builder-и realtime-провайдерів.
- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера,
а також helper-и онбордингу/конфігурації.
<Warning>
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
Якщо helper справді є спільним, підвищте його до нейтрального підшляху SDK,
Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
Якщо helper справді є спільним, перенесіть його до нейтрального підшляху SDK,
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
поверхні, орієнтованої на можливість, замість жорсткого зв’язування двох плагінів.
поверхні, орієнтованої на capability, замість зв’язування двох плагінів між собою.
</Warning>
## Пов’язане
## Пов’язані матеріали
<CardGroup cols={2}>
<Card title="Точки входу" icon="door-open" href="/uk/plugins/sdk-entrypoints">
Параметри `definePluginEntry` і `defineChannelPluginEntry`.
Опції `definePluginEntry` і `defineChannelPluginEntry`.
</Card>
<Card title="Хелпери runtime" icon="gears" href="/uk/plugins/sdk-runtime">
Повний довідник простору імен `api.runtime`.
<Card title="Допоміжні засоби runtime" icon="gears" href="/uk/plugins/sdk-runtime">
Повний довідник простору назв `api.runtime`.
</Card>
<Card title="Налаштування та конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
Пакування, маніфести та схеми конфігурації.
@ -341,7 +388,7 @@ helper навмисно є специфічним для провайдера і
<Card title="Міграція SDK" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
Міграція із застарілих поверхонь.
</Card>
<Card title="Внутрішня будова плагінів" icon="diagram-project" href="/uk/plugins/architecture">
Поглиблена архітектура та модель можливостей.
<Card title="Внутрішня архітектура плагінів" icon="diagram-project" href="/uk/plugins/architecture">
Поглиблена архітектура та модель capability.
</Card>
</CardGroup>