From 7b18427b61d4e96569a83ce4fca00410acbfdd1c Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 12:01:36 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/environment.md | 134 ++++++----- docs/uk/plugins/hooks.md | 281 ++++++++++------------ docs/uk/plugins/sdk-overview.md | 396 ++++++++++++++++---------------- 3 files changed, 389 insertions(+), 422 deletions(-) diff --git a/docs/uk/help/environment.md b/docs/uk/help/environment.md index cb6c4582c..93acea8ff 100644 --- a/docs/uk/help/environment.md +++ b/docs/uk/help/environment.md @@ -1,36 +1,36 @@ --- read_when: - Вам потрібно знати, які змінні середовища завантажуються і в якому порядку - - Ви налагоджуєте відсутні API-ключі в Gateway + - Ви налагоджуєте проблему з відсутніми ключами API у Gateway - Ви документуєте автентифікацію провайдера або середовища розгортання -summary: Звідки OpenClaw завантажує змінні середовища та порядок пріоритету +summary: Де OpenClaw завантажує змінні середовища та порядок пріоритетності title: Змінні середовища x-i18n: - generated_at: "2026-04-23T20:55:05Z" - model: gpt-5.4 + generated_at: "2026-04-28T11:59:57Z" + model: gpt-5.5 provider: openai - source_hash: b0538e07cc2f785224b5f061bdaee982c4c849838e9d637defcc86a5121710df + source_hash: d19b9053207a088b3eb39d03e36fc2d415295feb80da51bd71339884466b101b source_path: help/environment.md - workflow: 15 + workflow: 16 --- -OpenClaw отримує змінні середовища з кількох джерел. Правило таке: **ніколи не перевизначати наявні значення**. +OpenClaw отримує змінні середовища з кількох джерел. Правило: **ніколи не перевизначати наявні значення**. -## Пріоритет (від найвищого до найнижчого) +## Пріоритетність (найвища → найнижча) -1. **Середовище процесу** (те, що процес Gateway уже отримав від батьківської оболонки/демона). -2. **`.env` у поточному робочому каталозі** (типова поведінка dotenv; не перевизначає). -3. **Глобальний `.env`** у `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`; не перевизначає). -4. **Блок config `env`** у `~/.openclaw/openclaw.json` (застосовується лише за відсутності значення). -5. **Необов’язковий імпорт login-shell** (`env.shellEnv.enabled` або `OPENCLAW_LOAD_SHELL_ENV=1`), який застосовується лише для відсутніх очікуваних ключів. +1. **Середовище процесу** (те, що процес Gateway уже має від батьківської оболонки/демона). +2. **`.env` у поточному робочому каталозі** (стандарт dotenv; не перевизначає). +3. **Глобальний `.env`** у `~/.openclaw/.env` (також `$OPENCLAW_STATE_DIR/.env`; не перевизначає). +4. **Блок `env` конфігурації** у `~/.openclaw/openclaw.json` (застосовується лише якщо значення відсутнє). +5. **Необов'язковий імпорт login-shell** (`env.shellEnv.enabled` або `OPENCLAW_LOAD_SHELL_ENV=1`), застосовується лише для відсутніх очікуваних ключів. -На свіжих установленнях Ubuntu, які використовують типовий каталог стану, OpenClaw також розглядає `~/.config/openclaw/gateway.env` як сумісний резервний варіант після глобального `.env`. Якщо обидва файли існують і суперечать один одному, OpenClaw зберігає `~/.openclaw/.env` і виводить попередження. +На свіжих встановленнях Ubuntu, які використовують стандартний каталог стану, OpenClaw також розглядає `~/.config/openclaw/gateway.env` як сумісний резервний варіант після глобального `.env`. Якщо обидва файли існують і мають різні значення, OpenClaw залишає `~/.openclaw/.env` і виводить попередження. -Якщо файл конфігурації повністю відсутній, крок 4 пропускається; імпорт оболонки все одно виконується, якщо його ввімкнено. +Якщо файл конфігурації повністю відсутній, крок 4 пропускається; імпорт оболонки все одно запускається, якщо його ввімкнено. -## Блок config `env` +## Блок `env` конфігурації -Два еквівалентні способи задати inline env vars (обидва не перевизначають наявні значення): +Два рівнозначні способи встановити вбудовані змінні середовища (обидва не перевизначають): ```json5 { @@ -43,9 +43,9 @@ OpenClaw отримує змінні середовища з кількох дж } ``` -## Імпорт env оболонки +## Імпорт середовища оболонки -`env.shellEnv` запускає вашу login shell і імпортує лише **відсутні** очікувані ключі: +`env.shellEnv` запускає вашу оболонку входу й імпортує лише **відсутні** очікувані ключі: ```json5 { @@ -63,27 +63,27 @@ OpenClaw отримує змінні середовища з кількох дж - `OPENCLAW_LOAD_SHELL_ENV=1` - `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000` -## Env vars, ін’єктовані під час виконання +## Змінні середовища, впроваджені під час виконання -OpenClaw також ін’єктує маркери контексту в дочірні процеси, які він запускає: +OpenClaw також впроваджує контекстні маркери в породжені дочірні процеси: -- `OPENCLAW_SHELL=exec`: задається для команд, запущених через інструмент `exec`. -- `OPENCLAW_SHELL=acp`: задається для запусків процесів runtime-backend ACP (наприклад, `acpx`). -- `OPENCLAW_SHELL=acp-client`: задається для `openclaw acp client`, коли він запускає процес ACP bridge. -- `OPENCLAW_SHELL=tui-local`: задається для локальних команд оболонки `!` у TUI. +- `OPENCLAW_SHELL=exec`: встановлюється для команд, запущених через інструмент `exec`. +- `OPENCLAW_SHELL=acp`: встановлюється для породжених процесів бекенду середовища виконання ACP (наприклад `acpx`). +- `OPENCLAW_SHELL=acp-client`: встановлюється для `openclaw acp client`, коли він породжує процес моста ACP. +- `OPENCLAW_SHELL=tui-local`: встановлюється для локальних команд оболонки TUI `!`. -Це маркери часу виконання (а не обов’язкова конфігурація користувача). Їх можна використовувати в логіці shell/profile, -щоб застосовувати правила для конкретного контексту. +Це маркери часу виконання (не обов'язкова користувацька конфігурація). Їх можна використовувати в логіці оболонки/профілю +для застосування контекстно-специфічних правил. -## Env vars UI +## Змінні середовища інтерфейсу користувача -- `OPENCLAW_THEME=light`: примусово використовувати світлу палітру TUI, коли у вашого термінала світлий фон. -- `OPENCLAW_THEME=dark`: примусово використовувати темну палітру TUI. -- `COLORFGBG`: якщо ваш термінал експортує цю змінну, OpenClaw використовує підказку про колір фону, щоб автоматично вибрати палітру TUI. +- `OPENCLAW_THEME=light`: примусово вмикає світлу палітру TUI, коли ваш термінал має світле тло. +- `OPENCLAW_THEME=dark`: примусово вмикає темну палітру TUI. +- `COLORFGBG`: якщо ваш термінал експортує її, OpenClaw використовує підказку кольору тла для автоматичного вибору палітри TUI. -## Підстановка env vars у config +## Підстановка змінних середовища в конфігурації -Ви можете посилатися безпосередньо на env vars у рядкових значеннях config за допомогою синтаксису `${VAR_NAME}`: +Ви можете напряму посилатися на змінні середовища в рядкових значеннях конфігурації за допомогою синтаксису `${VAR_NAME}`: ```json5 { @@ -97,36 +97,36 @@ OpenClaw також ін’єктує маркери контексту в до } ``` -Повну інформацію див. в [Конфігурація: підстановка env vars](/uk/gateway/configuration-reference#env-var-substitution). +Повні подробиці див. у [Конфігурація: підстановка змінних середовища](/uk/gateway/configuration-reference#env-var-substitution). -## Secret refs проти рядків `${ENV}` +## Посилання на секрети й рядки `${ENV}` -OpenClaw підтримує два шаблони, що використовують env: +OpenClaw підтримує два шаблони на основі середовища: -- підстановку рядків `${VAR}` у значеннях config. -- об’єкти SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) для полів, що підтримують посилання на секрети. +- Рядкова підстановка `${VAR}` у значеннях конфігурації. +- Об'єкти SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) для полів, що підтримують посилання на секрети. -Обидва варіанти розв’язуються із середовища процесу під час активації. Докладніше про SecretRef див. у [Керування секретами](/uk/gateway/secrets). +Обидва розв'язуються із середовища процесу під час активації. Подробиці щодо SecretRef задокументовано в [Керуванні секретами](/uk/gateway/secrets). -## Env vars, пов’язані зі шляхами +## Змінні середовища, пов'язані зі шляхами -| Змінна | Призначення | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OPENCLAW_HOME` | Перевизначає домашній каталог, який використовується для всіх внутрішніх шляхів (`~/.openclaw/`, каталоги агентів, сесії, credentials). Корисно при запуску OpenClaw як окремого користувача сервісу. | -| `OPENCLAW_STATE_DIR` | Перевизначає каталог стану (типово `~/.openclaw`). | -| `OPENCLAW_CONFIG_PATH` | Перевизначає шлях до файла конфігурації (типово `~/.openclaw/openclaw.json`). | +| Змінна | Призначення | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OPENCLAW_HOME` | Перевизначає домашній каталог, що використовується для всього внутрішнього розв'язання шляхів (`~/.openclaw/`, каталоги агентів, сеанси, облікові дані). Корисно під час запуску OpenClaw як виділеного службового користувача. | +| `OPENCLAW_STATE_DIR` | Перевизначає каталог стану (стандартно `~/.openclaw`). | +| `OPENCLAW_CONFIG_PATH` | Перевизначає шлях до файлу конфігурації (стандартно `~/.openclaw/openclaw.json`). | ## Журналювання -| Змінна | Призначення | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OPENCLAW_LOG_LEVEL` | Перевизначає рівень журналювання і для файла, і для консолі (наприклад, `debug`, `trace`). Має пріоритет над `logging.level` і `logging.consoleLevel` у config. Некоректні значення ігноруються з попередженням. | +| Змінна | Призначення | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OPENCLAW_LOG_LEVEL` | Перевизначає рівень журналювання і для файлу, і для консолі (наприклад `debug`, `trace`). Має пріоритет над `logging.level` і `logging.consoleLevel` у конфігурації. Недійсні значення ігноруються з попередженням. | ### `OPENCLAW_HOME` -Коли задано, `OPENCLAW_HOME` замінює системний домашній каталог (`$HOME` / `os.homedir()`) для всіх внутрішніх шляхів. Це дає змогу повністю ізолювати файлову систему для headless-облікових записів сервісу. +Коли встановлено, `OPENCLAW_HOME` замінює системний домашній каталог (`$HOME` / `os.homedir()`) для всього внутрішнього розв'язання шляхів. Це забезпечує повну ізоляцію файлової системи для безголових службових облікових записів. -**Пріоритет:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()` +**Пріоритетність:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()` **Приклад** (macOS LaunchDaemon): @@ -138,18 +138,18 @@ OpenClaw підтримує два шаблони, що використовую ``` -`OPENCLAW_HOME` також можна задати як шлях із тильдою (наприклад, `~/svc`), який перед використанням розгортається через `$HOME`. +`OPENCLAW_HOME` також можна встановити як шлях із тильдою (наприклад `~/svc`), який перед використанням розгортається за допомогою `$HOME`. ## Користувачі nvm: збої TLS у web_fetch -Якщо Node.js було встановлено через **nvm** (а не через системний пакетний менеджер), вбудований `fetch()` використовує -вбудоване сховище CA від nvm, у якому можуть бракувати сучасних кореневих CA (ISRG Root X1/X2 для Let's Encrypt, -DigiCert Global Root G2 тощо). Через це `web_fetch` завершується з `"fetch failed"` на більшості HTTPS-сайтів. +Якщо Node.js було встановлено через **nvm** (а не системний менеджер пакунків), вбудований `fetch()` використовує +вбудоване сховище CA від nvm, у якому можуть бути відсутні сучасні кореневі CA (ISRG Root X1/X2 для Let's Encrypt, +DigiCert Global Root G2 тощо). Через це `web_fetch` завершується помилкою `"fetch failed"` на більшості сайтів HTTPS. -На Linux OpenClaw автоматично виявляє nvm і застосовує виправлення в реальному середовищі запуску: +У Linux OpenClaw автоматично виявляє nvm і застосовує виправлення у фактичному середовищі запуску: -- `openclaw gateway install` записує `NODE_EXTRA_CA_CERTS` у середовище сервісу systemd -- точка входу CLI `openclaw` повторно запускає себе з установленим `NODE_EXTRA_CA_CERTS` до старту Node +- `openclaw gateway install` записує `NODE_EXTRA_CA_CERTS` у середовище служби systemd +- точка входу CLI `openclaw` повторно запускає себе з установленим `NODE_EXTRA_CA_CERTS` до запуску Node **Ручне виправлення (для старіших версій або прямих запусків `node ...`):** @@ -160,11 +160,23 @@ export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt openclaw gateway run ``` -Не покладайтеся лише на запис цієї змінної в `~/.openclaw/.env`; Node зчитує -`NODE_EXTRA_CA_CERTS` під час старту процесу. +Не покладайтеся на запис лише в `~/.openclaw/.env` для цієї змінної; Node читає +`NODE_EXTRA_CA_CERTS` під час запуску процесу. -## Пов’язане +## Застарілі змінні середовища + +OpenClaw читає лише змінні середовища `OPENCLAW_*`. Застарілі +префікси `CLAWDBOT_*` і `MOLTBOT_*` з попередніх випусків мовчки +ігноруються. + +Якщо будь-які з них усе ще встановлені в процесі Gateway під час запуску, OpenClaw виводить +одне попередження Node про застарівання (`OPENCLAW_LEGACY_ENV_VARS`) зі списком +виявлених префіксів і загальною кількістю. Перейменуйте кожне значення, замінивши +застарілий префікс на `OPENCLAW_` (наприклад `CLAWDBOT_GATEWAY_TOKEN` → +`OPENCLAW_GATEWAY_TOKEN`); старі назви не мають жодного ефекту. + +## Пов'язане - [Конфігурація Gateway](/uk/gateway/configuration) -- [FAQ: env vars і завантаження .env](/uk/help/faq#env-vars-and-env-loading) +- [Поширені запитання: змінні середовища та завантаження .env](/uk/help/faq#env-vars-and-env-loading) - [Огляд моделей](/uk/concepts/models) diff --git a/docs/uk/plugins/hooks.md b/docs/uk/plugins/hooks.md index b30a2e213..494d82c34 100644 --- a/docs/uk/plugins/hooks.md +++ b/docs/uk/plugins/hooks.md @@ -1,30 +1,30 @@ --- read_when: - - Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу - - Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin - - Ви обираєте між внутрішніми хуками та хуками plugin -summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway' + - Ви створюєте Plugin, якому потрібні before_tool_call, before_agent_reply, хуки повідомлень або хуки життєвого циклу + - Потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із Plugin + - Ви обираєте між внутрішніми хуками та хуками Plugin +summary: 'Хуки Plugin: перехоплюйте події життєвого циклу агента, інструмента, повідомлення, сеансу та Gateway' title: Хуки Plugin x-i18n: - generated_at: "2026-04-28T00:34:03Z" - model: gpt-5.4 + generated_at: "2026-04-28T12:00:09Z" + model: gpt-5.5 provider: openai - source_hash: 689f4c15058f03cff1feb2a8aa1450c75cc3f8648d8ac7cc03ea952b3a1975bd + source_hash: 7aa6284ea4033fd0da624a794bf7b8b62c0d93d1a4a5a1f7146c8aa55a1dd1c3 source_path: plugins/hooks.md - workflow: 15 + workflow: 16 --- -Хуки Plugin — це внутрішньопроцесні точки розширення для plugin у OpenClaw. Використовуйте їх, -коли plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень, +Plugin hooks — це внутрішньопроцесні точки розширення для плагінів OpenClaw. Використовуйте їх, +коли плагіну потрібно переглядати або змінювати запуски агентів, виклики інструментів, потік повідомлень, життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway. -Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), якщо вам потрібен невеликий -встановлюваний оператором скрипт `HOOK.md` для подій команд і Gateway, таких як +Натомість використовуйте [внутрішні hooks](/uk/automation/hooks), коли потрібен невеликий +установлений оператором скрипт `HOOK.md` для команд і подій Gateway, таких як `/new`, `/reset`, `/stop`, `agent:bootstrap` або `gateway:startup`. ## Швидкий старт -Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` у точці входу вашого plugin: +Реєструйте типізовані plugin hooks за допомогою `api.on(...)` з точки входу вашого плагіна: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -56,66 +56,68 @@ export default definePluginEntry({ }); ``` -Обробники хуків виконуються послідовно у порядку спадання `priority`. Хуки з однаковим пріоритетом +Обробники hooks виконуються послідовно в порядку спадання `priority`. Hooks з однаковим пріоритетом зберігають порядок реєстрації. -Кожен хук отримує `event.context.pluginConfig` — обчислену конфігурацію для plugin, який зареєстрував цей обробник. Використовуйте її для рішень хуків, яким потрібні -поточні параметри plugin; OpenClaw додає її окремо для кожного обробника, не змінюючи -спільний об’єкт події, який бачать інші plugin. +Кожен hook отримує `event.context.pluginConfig`, вирішену конфігурацію для +плагіна, який зареєстрував цей обробник. Використовуйте її для рішень hook, яким потрібні +поточні параметри плагіна; OpenClaw впроваджує її окремо для кожного обробника, не змінюючи +спільний об’єкт події, який бачать інші плагіни. -## Каталог хуків +## Каталог hooks -Хуки згруповані за поверхнею, яку вони розширюють. Назви **жирним** приймають -результат рішення (блокування, скасування, перевизначення або вимога схвалення); усі інші -призначені лише для спостереження. +Hooks згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають +результат рішення (заблокувати, скасувати, перевизначити або вимагати схвалення); усі інші призначені +лише для спостереження. **Хід агента** - `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії -- `agent_turn_prepare` — спожити поставлені в чергу ін’єкції ходу plugin і додати контекст цього ж ходу перед хуками prompt +- `agent_turn_prepare` — спожити поставлені в чергу вставки ходу плагіна й додати контекст того самого ходу перед prompt hooks - `before_prompt_build` — додати динамічний контекст або текст системного prompt перед викликом моделі -- `before_agent_start` — сумісна об’єднана фаза; натомість віддавайте перевагу двом хукам вище -- **`before_agent_reply`** — замкнути хід моделі достроково синтетичною відповіддю або тишею -- **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі -- `agent_end` — спостерігати фінальні повідомлення, стан успішності та тривалість запуску -- `heartbeat_prompt_contribution` — додати контекст лише для heartbeat для фонових моніторів і plugin життєвого циклу +- `before_agent_start` — комбінована фаза лише для сумісності; віддавайте перевагу двом hooks вище +- **`before_agent_reply`** — коротко замкнути хід моделі синтетичною відповіддю або мовчанням +- **`before_agent_finalize`** — переглянути природну фінальну відповідь і запросити ще один прохід моделі +- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску +- `heartbeat_prompt_contribution` — додати контекст лише для heartbeat для фонових моніторів і плагінів життєвого циклу **Спостереження за розмовою** -- `model_call_started` / `model_call_ended` — спостерігати санітовані метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту prompt або відповіді -- `llm_input` — спостерігати вхід провайдера (системний prompt, prompt, історію) -- `llm_output` — спостерігати вихід провайдера +- `model_call_started` / `model_call_ended` — спостерігати санітизовані метадані виклику провайдера/моделі, таймінг, результат і обмежені хеші ідентифікаторів запитів без вмісту prompt або відповіді +- `llm_input` — спостерігати вхідні дані провайдера (системний prompt, prompt, історія) +- `llm_output` — спостерігати вихідні дані провайдера **Інструменти** - **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення - `after_tool_call` — спостерігати результати інструмента, помилки та тривалість -- **`tool_result_persist`** — переписати повідомлення помічника, створене з результату інструмента -- **`before_message_write`** — перевірити або заблокувати запис повідомлення, що виконується (рідко) +- **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента +- **`before_message_write`** — переглянути або заблокувати запис повідомлення в процесі (рідко) -**Повідомлення і доставка** +**Повідомлення та доставлення** -- **`inbound_claim`** — перехопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді) -- `message_received` — спостерігати вхідний вміст, відправника, потік і метадані -- **`message_sending`** — переписати вихідний вміст або скасувати доставку -- `message_sent` — спостерігати успіх або невдачу вихідної доставки -- **`before_dispatch`** — перевірити або переписати вихідне dispatch перед передачею каналу -- **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді +- **`inbound_claim`** — заявити права на вхідне повідомлення перед маршрутизацією агента (синтетичні відповіді) +- `message_received` — спостерігати вхідний вміст, відправника, thread і метадані +- **`message_sending`** — переписати вихідний вміст або скасувати доставлення +- `message_sent` — спостерігати успішне або невдале доставлення вихідного повідомлення +- **`before_dispatch`** — переглянути або переписати вихідне dispatch перед передаванням каналу +- **`reply_dispatch`** — брати участь у фінальному конвеєрі reply-dispatch -**Сесії та Compaction** +**Сесії та compaction** - `session_start` / `session_end` — відстежувати межі життєвого циклу сесії -- `before_compaction` / `after_compaction` — спостерігати або анотувати цикли Compaction +- `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` — запускати або зупиняти сервіси, що належать плагіну, разом із Gateway +- `cron_changed` — спостерігати зміни життєвого циклу cron, що належать gateway (додано, оновлено, видалено, запущено, завершено, заплановано) +- **`before_install`** — переглядати сканування встановлення skill або плагіна й за потреби блокувати ## Політика викликів інструментів @@ -126,9 +128,9 @@ export default definePluginEntry({ - необов’язковий `event.runId` - необов’язковий `event.toolCallId` - поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, - `ctx.runId`, `ctx.jobId` (встановлюється для запусків, ініційованих cron), і діагностичний `ctx.trace` + `ctx.runId`, `ctx.jobId` (задано для запусків, керованих cron), і діагностичний `ctx.trace` -Він може повертати: +Може повертати: ```typescript type BeforeToolCallResult = { @@ -151,85 +153,44 @@ type BeforeToolCallResult = { Правила: -- `block: true` є термінальним і пропускає обробники з нижчим пріоритетом. -- `block: false` вважається відсутністю рішення. +- `block: true` є кінцевим рішенням і пропускає обробники з нижчим пріоритетом. +- `block: false` трактується як відсутність рішення. - `params` переписує параметри інструмента для виконання. -- `requireApproval` призупиняє запуск агента і запитує користувача через схвалення plugin. - Команда `/approve` може схвалювати і exec-, і plugin-схвалення. -- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом - запросив схвалення. -- `onResolution` отримує підсумкове рішення щодо схвалення — `allow-once`, - `allow-always`, `deny`, `timeout` або `cancelled`. +- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin. Команда `/approve` може схвалювати як exec, так і схвалення plugin. +- `block: true` з нижчим пріоритетом усе ще може заблокувати виконання після того, як хук із вищим пріоритетом запросив схвалення. +- `onResolution` отримує вирішене рішення щодо схвалення — `allow-once`, `allow-always`, `deny`, `timeout` або `cancelled`. -Вбудовані plugin, яким потрібна політика на рівні хоста, можуть реєструвати довірені політики інструментів -за допомогою `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних -хуків `before_tool_call` і до рішень зовнішніх plugin. Використовуйте їх лише -для довірених на рівні хоста обмежень, таких як політика робочого простору, контроль бюджету або -безпека зарезервованих робочих процесів. Зовнішні plugin мають використовувати звичайні хуки `before_tool_call`. +Вбудовані plugins, яким потрібна політика рівня хоста, можуть реєструвати довірені політики інструментів за допомогою `api.registerTrustedToolPolicy(...)`. Вони виконуються перед звичайними хуками `before_tool_call` і перед рішеннями зовнішніх plugin. Використовуйте їх лише для довірених хостом обмежень, як-от політика робочого простору, контроль бюджету або безпека зарезервованих workflow. Зовнішні plugins мають використовувати звичайні хуки `before_tool_call`. ### Збереження результатів інструментів -Результати інструментів можуть містити структуровані `details` для рендерингу в UI, діагностики, -маршрутизації медіа або метаданих, якими володіє plugin. Розглядайте `details` як метадані виконання, -а не як вміст prompt: +Результати інструментів можуть містити структуровані `details` для рендерингу UI, діагностики, маршрутизації медіа або метаданих, що належать plugin. Розглядайте `details` як runtime-метадані, а не як вміст prompt: -- OpenClaw видаляє `toolResult.details` перед повторним програванням провайдеру та перед входом Compaction, - щоб метадані не ставали контекстом моделі. -- Збережені записи сесії містять лише обмежені `details`. Надмірно великі details - замінюються компактним підсумком і `persistedDetailsTruncated: true`. -- `tool_result_persist` і `before_message_write` виконуються до фінального - обмеження збереження. Усе ж хуки мають повертати невеликі `details` і уникати - розміщення тексту, важливого для prompt, лише в `details`; вивід інструмента, видимий моделі, - слід поміщати в `content`. +- OpenClaw вилучає `toolResult.details` перед повторним відтворенням у provider і вхідними даними compaction, щоб метадані не потрапляли в контекст моделі. +- Збережені записи сесії залишають лише обмежені `details`. Завеликі details замінюються компактним підсумком і `persistedDetailsTruncated: true`. +- `tool_result_persist` і `before_message_write` виконуються перед фінальним обмеженням збереження. Хуки все одно мають зберігати повернені `details` малими й уникати розміщення тексту, важливого для prompt, лише в `details`; вивід інструмента, видимий моделі, розміщуйте в `content`. ## Хуки prompt і моделі -Для нових plugin використовуйте хуки, специфічні для фази: +Для нових plugins використовуйте хуки, специфічні для фази: -- `before_model_resolve`: отримує лише поточний prompt і метадані вкладень. - Поверніть `providerOverride` або `modelOverride`. -- `agent_turn_prepare`: отримує поточний prompt, підготовлені повідомлення сесії - і будь-які ін’єкції, поставлені в чергу рівно один раз і вилучені для цієї сесії. Поверніть - `prependContext` або `appendContext`. -- `before_prompt_build`: отримує поточний prompt і повідомлення сесії. - Поверніть `prependContext`, `appendContext`, `systemPrompt`, - `prependSystemContext` або `appendSystemContext`. -- `heartbeat_prompt_contribution`: виконується лише для heartbeat-ходів і повертає - `prependContext` або `appendContext`. Він призначений для фонових моніторів, - яким потрібно підсумувати поточний стан без зміни ходів, ініційованих користувачем. +- `before_model_resolve`: отримує лише поточний prompt і метадані вкладень. Поверніть `providerOverride` або `modelOverride`. +- `agent_turn_prepare`: отримує поточний prompt, підготовлені повідомлення сесії та будь-які інʼєкції, поставлені в чергу точно один раз і вибрані для цієї сесії. Поверніть `prependContext` або `appendContext`. +- `before_prompt_build`: отримує поточний prompt і повідомлення сесії. Поверніть `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`. +- `heartbeat_prompt_contribution`: виконується лише для ходів Heartbeat і повертає `prependContext` або `appendContext`. Він призначений для фонових моніторів, яким потрібно підсумовувати поточний стан без зміни ходів, ініційованих користувачем. -`before_agent_start` залишається для сумісності. Віддавайте перевагу явним хукам вище, -щоб ваш plugin не залежав від застарілої об’єднаної фази. +`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 могли привʼязувати метрики, побічні ефекти або стан до конкретного запланованого завдання. -`agent_end` — це хук спостереження, який виконується у режимі fire-and-forget після ходу. Runner -хуків застосовує тайм-аут у 30 секунд, щоб завислий plugin або embedding- -endpoint не могли залишити promise хука назавжди в очікуванні. Тайм-аут логуються, і -OpenClaw продовжує роботу; це не скасовує мережеву роботу plugin, -якщо plugin також не використовує власний сигнал abort. +`agent_end` є хуком спостереження й виконується за принципом fire-and-forget після ходу. Виконавець хуків застосовує таймаут 30 секунд, щоб завислий plugin або endpoint embedding не залишив promise хуку в очікуванні назавжди. Таймаут записується в журнал, і OpenClaw продовжує роботу; він не скасовує мережеву роботу, що належить plugin, якщо plugin також не використовує власний сигнал abort. -Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера, -яка не повинна отримувати сирі prompt, історію, відповіді, заголовки, тіла -запитів або request ID провайдера. Ці хуки містять стабільні метадані, такі як -`runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, -фінальні `durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може отримати -обмежений хеш request-id провайдера. +Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів provider, яка не повинна отримувати сирі prompts, історію, відповіді, headers, тіла запитів або ідентифікатори запитів provider. Ці хуки містять стабільні метадані, як-от `runId`, `callId`, `provider`, `model`, необовʼязкові `api`/`transport`, кінцеві `durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може вивести обмежений хеш request-id provider. -`before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну -фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не виконується, -коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб -попросити harness зробити ще один прохід моделі перед фіналізацією, `{ action: -"finalize", reason? }`, щоб примусово фіналізувати, або не повертайте результат, -щоб продовжити. Вбудовані в Codex хуки `Stop` передаються в цей хук як рішення OpenClaw -`before_agent_finalize`. +`before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб попросити harness виконати ще один прохід моделі перед фіналізацією, `{ action: +"finalize", reason? }`, щоб примусово фіналізувати, або не повертайте результат, щоб продовжити. Нативні хуки Codex `Stop` передаються в цей хук як рішення OpenClaw `before_agent_finalize`. -Невбудовані plugin, яким потрібні `llm_input`, `llm_output`, -`before_agent_finalize` або `agent_end`, мають задати: +Невбудовані plugins, яким потрібні `llm_input`, `llm_output`, `before_agent_finalize` або `agent_end`, мають установити: ```json { @@ -245,100 +206,94 @@ OpenClaw продовжує роботу; це не скасовує мереж } ``` -Хуки, що змінюють prompt, і стійкі ін’єкції наступного ходу можна вимкнути для кожного plugin -через `plugins.entries..hooks.allowPromptInjection=false`. +Хуки, що змінюють prompt, і довговічні інʼєкції наступного ходу можна вимкнути для окремого plugin за допомогою `plugins.entries..hooks.allowPromptInjection=false`. -### Розширення сесії та ін’єкції наступного ходу +### Розширення сесії та інʼєкції наступного ходу -Plugin для workflow можуть зберігати невеликий JSON-сумісний стан сесії за допомогою -`api.registerSessionExtension(...)` і оновлювати його через метод Gateway -`sessions.pluginPatch`. Рядки сесій проєктують стан зареєстрованого розширення через -`pluginExtensions`, даючи змогу Control UI та іншим клієнтам відображати -стан, що належить plugin, без знання внутрішньої логіки plugin. +Workflow plugins можуть зберігати невеликий JSON-сумісний стан сесії за допомогою `api.registerSessionExtension(...)` і оновлювати його через метод Gateway `sessions.pluginPatch`. Рядки сесії проєктують зареєстрований стан розширення через `pluginExtensions`, даючи Control UI та іншим клієнтам змогу рендерити статус, що належить plugin, без знання внутрішньої реалізації plugin. -Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin має передати стійкий контекст -до наступного ходу моделі рівно один раз. OpenClaw вилучає поставлені в чергу ін’єкції перед -хуками prompt, відкидає прострочені ін’єкції та усуває дублікати за `idempotencyKey` -для кожного plugin. Це правильна точка розширення для відновлення після схвалень, підсумків політик, -дельт фонових моніторів і продовжень команд, які мають бути видимі -моделі на наступному ході, але не повинні ставати постійним текстом системного prompt. +Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin потрібен довговічний контекст, який має потрапити до наступного ходу моделі рівно один раз. OpenClaw вибирає поставлені в чергу інʼєкції перед хуками prompt, відкидає прострочені інʼєкції та дедуплікує за `idempotencyKey` для кожного plugin. Це правильний шов для відновлень після схвалення, підсумків політик, дельт фонових моніторів і продовжень команд, які мають бути видимі моделі на наступному ході, але не повинні ставати постійним текстом system prompt. -Семантика очищення є частиною контракту. Зворотні виклики очищення розширень сесії та очищення життєвого циклу runtime отримують `reset`, `delete`, `disable` або -`restart`. Хост видаляє стан постійного розширення сесії та очікувані ін’єкції наступного ходу, -що належать plugin, для `reset`/`delete`/`disable`; `restart` зберігає стійкий стан сесії, тоді як зворотні виклики очищення дають plugin змогу звільнити завдання планувальника, -контекст запуску та інші зовнішні ресурси старого покоління runtime. +Семантика очищення є частиною контракту. Очищення розширень сесії та callbacks очищення життєвого циклу runtime отримують `reset`, `delete`, `disable` або `restart`. Хост видаляє постійний стан розширення сесії plugin-власника та очікувані інʼєкції наступного ходу для reset/delete/disable; restart зберігає довговічний стан сесії, тоді як callbacks очищення дають plugins змогу звільняти завдання scheduler, контекст запуску та інші позасмугові ресурси для старого покоління runtime. ## Хуки повідомлень Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки: -- `message_received`: спостерігати вхідний вміст, відправника, `threadId`, `messageId`, - `senderId`, необов’язкову кореляцію запуску/сесії та метадані. -- `message_sending`: переписати `content` або повернути `{ cancel: true }`. -- `message_sent`: спостерігати фінальний успіх або невдачу. +- `message_received`: спостерігає вхідний вміст, відправника, `threadId`, `messageId`, `senderId`, необовʼязкову кореляцію запуску/сесії та метадані. +- `message_sending`: переписує `content` або повертає `{ cancel: true }`. +- `message_sent`: спостерігає фінальний успіх або невдачу. -Для TTS-відповідей лише з аудіо `content` може містити прихований озвучений транскрипт, -навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього -`content` оновлює лише транскрипт, видимий хуку; він не відображається як -підпис медіа. +Для audio-only TTS-відповідей `content` може містити прихований озвучений transcript, навіть коли payload каналу не має видимого тексту/caption. Переписування цього `content` оновлює лише transcript, видимий хукам; він не рендериться як media caption. Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні: `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` вважається відсутністю рішення. -- Переписаний `content` передається хукам із нижчим пріоритетом, якщо пізніший хук - не скасує доставку. +- Переписаний `content` продовжує передаватися хукам нижчого пріоритету, якщо + пізніший хук не скасує доставлення. -## Хуки встановлення +## Установлення хуків -`before_install` виконується після вбудованого сканування встановлень skill і plugin. -Поверніть додаткові результати перевірки або `{ block: true, blockReason }`, щоб зупинити +`before_install` виконується після вбудованого сканування для встановлення Skills і Plugin. +Поверніть додаткові знахідки або `{ block: true, blockReason }`, щоб зупинити встановлення. `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` для runtime-сервісів, що належать plugin. +Не покладайтеся на внутрішній хук `gateway:startup` для runtime-сервісів, що належать Plugin. + +`cron_changed` спрацьовує для подій життєвого циклу Cron, що належать Gateway, з типізованим +payload події, який охоплює причини `added`, `updated`, `removed`, `started`, `finished` +і `scheduled`. Подія містить знімок `PluginHookGatewayCronJob` +(зокрема `state.nextRunAtMs`, `state.lastRunStatus` і +`state.lastError`, коли наявні), а також `PluginHookGatewayCronDeliveryStatus` +зі значеннями `not-requested` | `delivered` | `not-delivered` | `unknown`. Події видалення +все одно містять знімок видаленого завдання, щоб зовнішні планувальники могли +узгодити стан. Використовуйте `ctx.getCron?.()` і `ctx.config` із runtime-контексту +під час синхронізації зовнішніх планувальників пробудження та залишайте OpenClaw +джерелом істини для перевірок настання строку й виконання. ## Майбутні застарівання -Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Перейдіть -на нові варіанти до наступного мажорного релізу: +Кілька поверхонь, суміжних із хуками, застаріли, але все ще підтримуються. Перейдіть +на нові підходи до наступного мажорного випуску: -- **Конверти каналів у відкритому тексті** в обробниках `inbound_claim` і `message_received`. +- **Plaintext channel envelopes** в обробниках `inbound_claim` і `message_received`. Читайте `BodyForAgent` і структуровані блоки контексту користувача - замість розбору плоского тексту конверта. Див. - [Конверти каналів у відкритому тексті → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). -- **`before_agent_start`** залишається для сумісності. Нові plugin повинні використовувати + замість розбору плоского тексту envelope. Див. + [Plaintext channel envelopes → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). +- **`before_agent_start`** лишається для сумісності. Нові Plugin мають використовувати `before_model_resolve` і `before_prompt_build` замість об’єднаної фази. -- **`onResolution` у `before_tool_call`** тепер використовує типізоване - об’єднання `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / +- **`onResolution` у `before_tool_call`** тепер використовує типізований + union `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) замість довільного `string`. -Повний список — реєстрація можливостей пам’яті, профіль thinking провайдера, -зовнішні провайдери автентифікації, типи виявлення провайдера, runtime-аксесори завдань -і перейменування `command-auth` → `command-status` — див. у +Повний список — реєстрація memory capability, профіль мислення провайдера, +зовнішні провайдери автентифікації, типи виявлення провайдерів, accessors runtime завдань +і перейменування `command-auth` → `command-status` — див. [Міграція Plugin SDK → Активні застарівання](/uk/plugins/sdk-migration#active-deprecations). ## Пов’язане -- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та часові рамки видалення -- [Створення plugin](/uk/plugins/building-plugins) +- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та графік видалення +- [Створення Plugin](/uk/plugins/building-plugins) - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Точки входу Plugin](/uk/plugins/sdk-entrypoints) - [Внутрішні хуки](/uk/automation/hooks) -- [Внутрішня архітектура plugin](/uk/plugins/architecture-internals) +- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals) diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 9fb199c1b..2d3770d16 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -4,25 +4,25 @@ read_when: - Вам потрібен довідник усіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Карта імпорту, довідник API реєстрації та архітектура SDK +summary: Карта імпортів, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-28T11:20:02Z" + generated_at: "2026-04-28T12:00:02Z" model: gpt-5.5 provider: openai - source_hash: c45d0ef57427b89a51b872b54b2c3ef2674c27d22d7e7744809ed35d1b1d02af + source_hash: 0c3bd7ae2ca2fbf351442bfd073450b72368e1ab833dbbdccfbe569db5346ce9 source_path: plugins/sdk-overview.md workflow: 16 --- SDK плагінів є типізованим контрактом між плагінами та ядром. Ця сторінка є -довідником щодо **того, що імпортувати** і **що можна реєструвати**. +довідником про **що імпортувати** та **що можна реєструвати**. -Шукаєте натомість практичний посібник? Почніть із [створення плагінів](/uk/plugins/building-plugins), використовуйте [плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу. +Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу. -## Угода імпорту +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -33,157 +33,157 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; Кожен підшлях є невеликим самодостатнім модулем. Це зберігає швидкий запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу помічників входу/збирання -надавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої парасолькової поверхні та спільних помічників, як-от +віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +ширшої загальної поверхні та спільних помічників, як-от `buildChannelConfigSchema`. Для конфігурації каналу публікуйте JSON Schema, якою володіє канал, через `openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema` -призначений для спільних примітивів схем і загального конструктора. Вбудовані +призначений для спільних примітивів схем і універсального збирача. Вбудовані плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених схем вбудованих каналів. Застарілі експорти сумісності залишаються в -`plugin-sdk/channel-config-schema-legacy`; жоден підшлях вбудованих схем не є +`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не є шаблоном для нових плагінів. - Не імпортуйте брендовані провайдером або каналом зручні шви (наприклад + Не імпортуйте провайдеро- або канально-брендовані зручні шви (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни компонують загальні підшляхи SDK усередині власних барелів `api.ts` / + Вбудовані плагіни компонують універсальні підшляхи SDK усередині власних барелів `api.ts` / `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для плагіна - барели, або додати вузький загальний контракт SDK, коли потреба справді є + барели, або додати вузький універсальний контракт SDK, коли потреба справді є міжканальною. -Невеликий набір допоміжних швів для вбудованих плагінів усе ще з'являється у згенерованій карті -експортів, коли вони мають відстежене використання власником. Вони існують лише для -супроводу вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх +Невеликий набір допоміжних швів для вбудованих плагінів усе ще з’являється в згенерованій мапі експортів, +коли для них відстежено використання власником. Вони існують лише для супроводу вбудованих плагінів +і не рекомендовані як шляхи імпорту для нових сторонніх плагінів. ## Довідник підшляхів -SDK плагінів надається як набір вузьких підшляхів, згрупованих за областями (вхід -плагіна, канал, провайдер, автентифікація, середовище виконання, можливість, пам'ять і зарезервовані -помічники вбудованих плагінів). Повний каталог, згрупований і з посиланнями, див. -у [підшляхах SDK Plugin](/uk/plugins/sdk-subpaths). +SDK плагінів експонується як набір вузьких підшляхів, згрупованих за областями (вхід +плагіна, канал, провайдер, автентифікація, runtime, можливість, пам’ять і зарезервовані +помічники вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див. +[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Зворотний виклик `register(api)` отримує об'єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Метод | Що він реєструє | +| Метод | Що він реєструє | | ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | +| `api.registerProvider(...)` | Текстове виведення (LLM) | | `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний бекенд виведення CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез тексту в мовлення / STT | +| `api.registerCliBackend(...)` | Локальний CLI-бекенд виведення | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Text-to-speech / STT-синтез | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер веботримання / скрейпінгу | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер веб-отримання / скрейпінгу | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що він реєструє | +| Метод | Що він реєструє | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Інструмент агента (обов'язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | -Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка -підказка маршрутизації, що належить команді. Тримайте цей текст про саму команду; не додавайте -специфічну для провайдера чи плагіна політику до конструкторів промптів ядра. +Команди плагінів можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка, +керована командою підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте +політику, специфічну для провайдера або плагіна, до збирачів промптів ядра. ### Інфраструктура -| Метод | Що він реєструє | +| Метод | Що він реєструє | | ---------------------------------------------- | --------------------------------------- | -| `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(...)` | Проміжне ПЗ результатів інструментів середовища виконання | -| `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 middleware результатів інструментів | +| `api.registerMemoryPromptSupplement(builder)` | Додатковий суміжний із пам’яттю розділ промпта | +| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | -### Хост-хуки для плагінів робочих процесів +### Хостові хуки для плагінів workflow -Хост-хуки є швами SDK для плагінів, яким потрібно брати участь у життєвому циклі -хоста, а не лише додавати провайдера, канал або інструмент. Вони є -загальними контрактами; Plan Mode може їх використовувати, але так само можуть робочі процеси затвердження, -шлюзи політик робочого простору, фонові монітори, майстри налаштування й супутні UI -плагіни. +Хостові хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста, +а не лише додавати провайдера, канал або інструмент. Це +універсальні контракти; Plan Mode може їх використовувати, але так само можуть workflow затвердження, +гейти політик робочого простору, фонові монітори, майстри налаштування та супровідні UI-плагіни. -| Метод | Контракт, яким він володіє | +| Метод | Контракт, яким він володіє | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | Належний плагіну JSON-сумісний стан сеансу, проєктований через сеанси Gateway | -| `api.enqueueNextTurnInjection(...)` | Довговічний контекст рівно-один-раз, введений у наступний хід агента для одного сеансу | -| `api.registerTrustedToolPolicy(...)` | Політика інструментів до плагінів для вбудованих/довірених, яка може блокувати або переписувати параметри інструментів | -| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | -| `api.registerCommand(...)` | Команди з областю дії плагіна; результати команд можуть задавати `continueAgent: true` | -| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сеансу, інструмента, запуску або налаштувань | -| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для належних плагіну ресурсів середовища виконання на шляхах скидання/видалення/перезавантаження | -| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану робочого процесу та моніторів | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Тимчасовий стан плагіна на запуск, очищений під час термінального життєвого циклу запуску | -| `api.registerSessionSchedulerJob(...)` | Належні плагіну записи завдань планувальника сеансів із детермінованим очищенням | +| `api.registerSessionExtension(...)` | Стан сесії, яким володіє плагін і який сумісний із JSON, проєктований через сесії Gateway | +| `api.enqueueNextTurnInjection(...)` | Стійкий контекст exactly-once, вставлений у наступний хід агента для однієї сесії | +| `api.registerTrustedToolPolicy(...)` | Вбудована/довірена політика інструментів до плагінів, що може блокувати або переписувати параметри інструмента | +| `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-дескрипторами, командами, метаданими інструментів, ін'єкціями наступного ходу та звичайними хуками. -- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише вбудованим плагінам, оскільки вони беруть участь у політиці безпеки хоста. -- Зарезервоване володіння командами доступне лише вбудованим плагінам. Зовнішні плагіни мають використовувати власні назви команд або псевдоніми. +- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними хуками. +- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і є лише вбудованими, бо беруть участь у політиці безпеки хоста. +- Зарезервоване володіння командами є лише вбудованим. Зовнішні плагіни мають використовувати + власні назви команд або псевдоніми. - `allowPromptInjection=false` вимикає хуки, що змінюють промпт, зокрема `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, - поля промпта зі спадкового `before_agent_start` та + поля промпта зі спадкового `before_agent_start` і `enqueueNextTurnInjection`. -Приклади споживачів поза Plan: +Приклади споживачів, що не належать до Plan: -| Архетип Plugin | Використані хуки | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -| Робочий процес затвердження | Розширення сеансу, продовження команди, ін'єкція наступного ходу, UI-дескриптор | -| Шлюз політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сеансу | -| Фоновий монітор життєвого циклу | Очищення життєвого циклу середовища виконання, підписка на події агента, володіння/очищення планувальника сеансів, внесок промпта Heartbeat, UI-дескриптор | -| Майстер налаштування або онбордингу | Розширення сеансу, команди з областю дії, дескриптор Control UI | +| Архетип плагіна | Використані хуки | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Workflow затвердження | Розширення сесії, продовження команди, ін’єкція наступного ходу, UI-дескриптор | +| Гейт політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії | +| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок до промпта Heartbeat, UI-дескриптор | +| Майстер налаштування або онбордингу | Розширення сесії, обмежені за областю команди, дескриптор Control UI | - Зарезервовані простори назв адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити - вужчу область дії методу Gateway. Надавайте перевагу специфічним для плагіна префіксам для + вужчу область методу gateway. Віддавайте перевагу специфічним для плагіна префіксам для методів, якими володіє плагін. - + Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли - їм потрібно переписати результат інструмента після виконання і до того, як середовище виконання - передасть цей результат назад у модель. Це довірений нейтральний до середовища виконання + їм потрібно переписати результат інструмента після виконання й до того, як runtime + передасть цей результат назад у модель. Це довірений runtime-нейтральний шов для асинхронних редукторів виводу, таких як tokenjuice. Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного -цільового середовища виконання, наприклад `["pi", "codex"]`. Зовнішні плагіни -не можуть реєструвати це проміжне ПЗ; залишайте звичайні хуки плагінів OpenClaw для роботи, -яка не потребує таймінгу результату інструмента перед моделлю. Старий вбудований шлях -реєстрації фабрики розширень лише для Pi видалено. +цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни +не можуть реєструвати це middleware; залишайте звичайні хуки плагінів OpenClaw для роботи, +яка не потребує таймінгу результатів інструментів перед моделлю. Старий лише Pi-вбудований +шлях реєстрації фабрики розширення було видалено. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає плагіну змогу оголошувати активний -Gateway у локальному транспорті виявлення, як-от mDNS/Bonjour. OpenClaw викликає -службу під час запуску Gateway, коли локальне виявлення ввімкнено, передає -поточні порти Gateway і несекретні TXT-підказки, а також викликає повернений -обробник `stop` під час завершення роботи Gateway. +`api.registerGatewayDiscoveryService(...)` дає змогу плагіну рекламувати активний +Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає +сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає +поточні порти Gateway і несекретні дані підказок TXT, а також викликає повернений +обробник `stop` під час вимкнення Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -199,21 +199,21 @@ api.registerGatewayDiscoveryService({ }); ``` -Плагіни виявлення Gateway не повинні вважати оголошені TXT-значення секретами або -автентифікацією. Виявлення є підказкою маршрутизації; автентифікація Gateway і закріплення TLS усе ще -відповідають за довіру. +Плагіни виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або +автентифікацію. Виявлення є підказкою маршрутизації; довірою все ще володіють +автентифікація Gateway і TLS pinning. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє реєстратор -- `descriptors`: дескриптори команд часу розбору, які використовуються для кореневої довідки CLI, - маршрутизації та ледачої реєстрації CLI плагіна +- `commands`: явні корені команд, якими володіє registrar +- `descriptors`: дескриптори команд часу парсингу, що використовуються для кореневої довідки CLI, + маршрутизації та лінивої реєстрації CLI плагіна -Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному кореневому шляху CLI, -надайте `descriptors`, які покривають кожен кореневий елемент команди верхнього рівня, відкритий цим -реєстратором. +Якщо ви хочете, щоб команда Plugin залишалася lazy-loaded у звичайному кореневому шляху CLI, +надайте `descriptors`, які охоплюють кожен кореневий top-level command, що його відкриває цей +реєстратор. ```typescript api.registerCli( @@ -233,97 +233,97 @@ api.registerCli( ); ``` -Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива коренева реєстрація CLI. -Цей енергійний шлях сумісності й надалі підтримується, але він не встановлює -заповнювачі на основі дескрипторів для лінивого завантаження під час розбору. +Використовуйте лише `commands` тільки тоді, коли вам не потрібна lazy root CLI registration. +Цей eager compatibility path залишається підтримуваним, але він не встановлює +descriptor-backed placeholders для lazy loading під час parsing. -### Реєстрація бекенда CLI +### Реєстрація бекенду CLI -`api.registerCliBackend(...)` дає змогу Plugin володіти конфігурацією за замовчуванням для локального -бекенда AI CLI, такого як `codex-cli`. +`api.registerCliBackend(...)` дає змогу Plugin володіти типовою конфігурацією для локального +AI CLI backend, такого як `codex-cli`. -- `id` бекенда стає префіксом провайдера в посиланнях на моделі на кшталт `codex-cli/gpt-5`. -- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - стандартного значення Plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування сумісності після об’єднання - (наприклад, нормалізація старих форм прапорців). +- Backend `id` стає provider prefix у model refs на кшталт `codex-cli/gpt-5`. +- Backend `config` використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх + типового значення Plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує compatibility rewrites після merge + (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Рушій контексту (один активний за раз). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення підказки. | -| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Побудовник розділу підказки пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | +| Метод | Що він реєструє | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Context engine (один активний одночасно). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. | +| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Builder секції prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті | +| `api.registerMemoryRuntime(runtime)` | Runtime adapter пам’яті | -### Адаптери вбудовувань пам’яті +### Адаптери embedding пам’яті -| Метод | Що він реєструє | -| ---------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер вбудовувань пам’яті для активного Plugin | +| Метод | Що він реєструє | +| ---------------------------------------------- | ------------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного Plugin | -- `registerMemoryCapability` є рекомендованим ексклюзивним API для Plugin пам’яті. +- `registerMemoryCapability` є пріоритетним ексклюзивним API для memory-plugin. - `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, - щоб супутні Plugin могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури - конкретного Plugin пам’яті. + щоб супровідні plugins могли споживати експортовані artifacts пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість доступу до приватної структури конкретного + memory plugin. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні зі спадщиною ексклюзивні API для Plugin пам’яті. -- `MemoryFlushPlan.model` може закріпити хід скидання за точним посиланням - `provider/model`, таким як `ollama/qwen3:8b`, без успадкування активного ланцюга - резервних варіантів. -- `registerMemoryEmbeddingProvider` дає активному Plugin пам’яті змогу зареєструвати один - або кілька ідентифікаторів адаптерів вбудовувань (наприклад, `openai`, `gemini` або власний - ідентифікатор, визначений Plugin). + `registerMemoryRuntime` є legacy-compatible ексклюзивними API для memory-plugin. +- `MemoryFlushPlan.model` може прив’язати flush turn до точного посилання `provider/model`, + такого як `ollama/qwen3:8b`, без успадкування активного fallback chain. +- `registerMemoryEmbeddingProvider` дає активному memory plugin змогу зареєструвати один + або більше id адаптерів embedding (наприклад, `openai`, `gemini` або custom + plugin-defined id). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих - ідентифікаторів адаптерів. + `agents.defaults.memorySearch.fallback`, resolve проти цих зареєстрованих + id адаптерів. ### Події та життєвий цикл -| Метод | Що він робить | -| -------------------------------------------- | ------------------------------ | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | +| Метод | Що він робить | +| -------------------------------------------- | -------------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Callback прив’язки розмови | -Див. [Хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики захисту. +Див. [хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв hook і семантики guard. -### Семантика рішень хуків +### Семантика рішень 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`), а не як перевизначення. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідної гілки/теми. Залишайте `metadata` для додаткових даних, специфічних для каналу. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`. +- `before_tool_call`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override. +- `before_install`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override. +- `reply_dispatch`: повернення `{ handled: true, ... }` є terminal. Щойно будь-який handler claims dispatch, handlers із нижчим пріоритетом і default model dispatch path пропускаються. +- `message_sending`: повернення `{ cancel: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як omission `cancel`), а не як override. +- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для channel-specific extras. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId` перед fallback до channel-specific `metadata`. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для startup state, яким володіє Gateway, замість покладання на внутрішні hooks `gateway:startup`. +- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх wake schedulers, і залишайте OpenClaw джерелом істини для due checks та виконання. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор Plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія Plugin (необов’язково) | -| `api.description` | `string?` | Опис Plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела Plugin | -| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для Plugin, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Помічники середовища виконання](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю дії (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом | -| `api.resolvePath(input)` | `(string) => string` | Розв’язує шлях відносно кореня Plugin | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Id Plugin | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія Plugin (опційно) | +| `api.description` | `string?` | Опис Plugin (опційно) | +| `api.source` | `string` | Шлях джерела Plugin | +| `api.rootDir` | `string?` | Кореневий каталог Plugin (опційно) | +| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний in-memory runtime snapshot, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для Plugin, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` є lightweight pre-full-entry startup/setup window | +| `api.resolvePath(input)` | `(string) => string` | Resolve path відносно кореня Plugin | -## Внутрішня конвенція модулів +## Внутрішня домовленість щодо модулів -У межах вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +У межах вашого Plugin використовуйте local barrel files для внутрішніх imports: ``` my-plugin/ @@ -335,34 +335,34 @@ my-plugin/ Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` - з виробничого коду. Спрямовуйте внутрішні імпорти через `./api.ts` або - `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. + з production code. Спрямовуйте внутрішні imports через `./api.ts` або + `./runtime-api.ts`. Шлях SDK є лише зовнішнім contract. -Публічні поверхні вбудованих Plugin, завантажені через фасад (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні вхідні файли), віддають перевагу -активному знімку конфігурації середовища виконання, коли OpenClaw уже запущено. Якщо знімка середовища виконання -ще немає, вони повертаються до розв’язаної конфігурації з файлу на диску. -Фасади запакованих вбудованих Plugin слід завантажувати через завантажувачі фасадів OpenClaw SDK; -прямі імпорти з `dist/extensions/...` оминають поетапні дзеркала залежностей середовища виконання, -які запаковані встановлення використовують для залежностей, що належать Plugin. +Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні public entry files) надають перевагу +активному runtime config snapshot, коли OpenClaw уже запущений. Якщо runtime +snapshot ще не існує, вони fallback до resolved config file на диску. +Packaged bundled plugin facades слід завантажувати через facade loaders OpenClaw SDK; +прямі imports з `dist/extensions/...` обходять staged runtime dependency mirrors, +які packaged installs використовують для plugin-owned dependencies. -Provider Plugin можуть відкривати вузький локальний для Plugin контрактний barrel, коли -помічник навмисно специфічний для провайдера й поки не належить до універсального підшляху SDK. -Вбудовані приклади: +Provider plugins можуть відкривати вузький plugin-local contract barrel, коли +helper навмисно provider-specific і ще не належить до generic SDK +subpath. Bundled examples: -- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для Claude - beta-header і stream-помічників `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдера, - помічники моделей за замовчуванням і побудовники провайдера реального часу. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера - разом із помічниками онбордингу/конфігурації. +- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude + beta-header і stream helpers `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує provider builders, + default-model helpers і realtime provider builders. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує provider builder + плюс onboarding/config helpers. - Виробничий код розширення також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо помічник справді спільний, підніміть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша - поверхня, орієнтована на можливості, замість зв’язування двох Plugin між собою. + Production code розширення також має уникати imports `openclaw/plugin-sdk/`. + Якщо helper справді спільний, підвищте його до нейтрального SDK subpath, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + capability-oriented surface замість coupling двох plugins разом. ## Пов’язане @@ -371,19 +371,19 @@ Provider Plugin можуть відкривати вузький локальн Параметри `definePluginEntry` і `defineChannelPluginEntry`. - - Повний довідник простору імен `api.runtime`. + + Повний довідник namespace `api.runtime`. - - Пакування, маніфести та схеми конфігурації. + + Packaging, manifests і config schemas. - Тестові утиліти та правила lint. + Test utilities і lint rules. - Міграція із застарілих поверхонь. + Міграція з deprecated surfaces. - Поглиблена архітектура та модель можливостей. + Глибока архітектура та capability model.