diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index 136c2d219..9dd801917 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,38 +1,38 @@ --- read_when: - Встановлення або налаштування плагінів - - Розуміння правил виявлення та завантаження Plugin + - Розуміння правил виявлення й завантаження Plugin - Робота з пакетами Plugin, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлення, налаштування та керування Plugin-ами OpenClaw -title: Плагіни +summary: Встановлення, налаштування та керування плагінами OpenClaw +title: Plugins x-i18n: - generated_at: "2026-05-01T20:43:14Z" + generated_at: "2026-05-01T21:00:17Z" model: gpt-5.5 provider: openai - source_hash: 0991eac5bc54f7f5e0446747c7f9b81cce0a279e30412af53ce7b66539952708 + source_hash: 32e89479c899f05756ba2853728ff9428e1b0ef866d336bba721a962f5546a8b source_path: tools/plugin.md workflow: 16 --- -Плагіни розширюють OpenClaw новими можливостями: каналами, постачальниками моделей, -агентними середовищами, інструментами, Skills, мовленням, транскрипцією в реальному часі, -голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, web fetch, web -search та іншим. Деякі плагіни є **основними** (постачаються з OpenClaw), інші -є **зовнішніми**. Більшість зовнішніх плагінів публікуються й знаходяться через +Plugin розширюють OpenClaw новими можливостями: канали, постачальники моделей, +оболонки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, +голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, +отримання вебданих, вебпошук тощо. Деякі Plugin є **основними** (постачаються з OpenClaw), інші +є **зовнішніми**. Більшість зовнішніх Plugin публікуються та знаходяться через [ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для -тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується. +тимчасового набору пакетів Plugin, що належать OpenClaw, доки ця міграція завершується. ## Швидкий старт - + ```bash openclaw plugins list ``` - + ```bash # From npm openclaw plugins install npm:@acme/openclaw-plugin @@ -52,11 +52,11 @@ search та іншим. Деякі плагіни є **основними** (п openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. + Потім налаштуйте в `plugins.entries.\.config` у вашому конфігураційному файлі. - + ```bash openclaw plugins inspect --runtime --json @@ -64,9 +64,9 @@ search та іншим. Деякі плагіни є **основними** (п openclaw --help ``` - Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, сервіси, gateway - методи, хуки або CLI-команди, що належать плагіну. Звичайний `inspect` — це холодна - перевірка маніфесту/реєстру, яка навмисно уникає імпорту runtime плагіна. + Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, служби, gateway + методи, хуки або CLI-команди, що належать Plugin. Звичайний `inspect` є холодною + перевіркою маніфесту/реєстру й навмисно не імпортує runtime Plugin. @@ -79,65 +79,65 @@ search та іншим. Деякі плагіни є **основними** (п /plugin enable ``` -Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний -`clawhub:`, явний `npm:`, явний `git:` або специфікація пакета без префікса -(спочатку ClawHub, потім fallback на npm). +Шлях встановлення використовує той самий розв’язувач, що й CLI: локальний шлях/архів, явний +`clawhub:`, явний `npm:`, явний `git:` або проста специфікація пакета +(спочатку ClawHub, потім запасний варіант npm). -Якщо конфігурація недійсна, встановлення зазвичай завершується закритою відмовою й спрямовує вас до -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-plugin -для плагінів, які явно погодилися на +Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується помилкою і скеровує вас до +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях +перевстановлення вбудованих Plugin для Plugin, які погоджуються на `openclaw.install.allowInvalidConfigRecovery`. -Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється до цього плагіна: -запуск записує проблему `plugins.entries..config` у логи, пропускає цей плагін під час -завантаження й залишає інші плагіни та канали онлайн. Запустіть `openclaw doctor --fix`, -щоб помістити погану конфігурацію плагіна в карантин, вимкнувши цей запис плагіна й видаливши -його недійсний config payload; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на плагін, який більше не можна знайти, але той самий -застарілий id плагіна залишається в конфігурації плагіна або записах встановлення, запуск Gateway -записує попередження в логи й пропускає цей канал замість блокування всіх інших каналів. -Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі -ключі каналів без доказів застарілого плагіна все ще провалюють валідацію, щоб помилки введення -залишалися видимими. -Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються інертними: -запуск Gateway пропускає роботу з виявлення/завантаження плагінів, а `openclaw doctor` зберігає -вимкнену конфігурацію плагінів замість автоматичного видалення. Знову ввімкніть плагіни перед -запуском очищення doctor, якщо хочете видалити застарілі id плагінів. +Під час запуску Gateway недійсна конфігурація одного Plugin ізолюється до цього Plugin: +запуск записує в журнали проблему `plugins.entries..config`, пропускає цей Plugin під час +завантаження й залишає інші Plugin та канали онлайн. Запустіть `openclaw doctor --fix`, +щоб помістити погану конфігурацію Plugin у карантин, вимкнувши цей запис Plugin і видаливши +його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення. +Коли конфігурація каналу посилається на Plugin, який більше не вдається знайти, але той самий +застарілий ідентифікатор Plugin залишається в конфігурації Plugin або записах встановлення, запуск Gateway +записує попередження в журнали й пропускає цей канал замість блокування всіх інших каналів. +Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/Plugin; невідомі +ключі каналів без доказів застарілого Plugin все одно не проходять валідацію, щоб помилки введення залишалися +видимими. +Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugin вважаються інертними: +запуск Gateway пропускає роботу з виявлення/завантаження Plugin, а `openclaw doctor` зберігає +вимкнену конфігурацію Plugin замість автоматичного видалення. Повторно увімкніть Plugin перед +запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори Plugin. -Встановлення залежностей плагінів відбувається лише під час явних потоків install/update або -repair у doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція -не запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні плагіни вже мають -мати встановлені залежності, тоді як npm, git і ClawHub плагіни встановлюються -в керовані корені плагінів OpenClaw із package-local -залежностями. Зовнішні плагіни й користувацькі шляхи завантаження все одно мають бути встановлені +Встановлення залежностей Plugin відбувається лише під час явних потоків встановлення/оновлення або +відновлення doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція не +запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні Plugin уже повинні +мати встановлені залежності, тоді як npm, git і ClawHub Plugin +встановлюються під керованими коренями Plugin OpenClaw із локальними для пакета +залежностями. Зовнішні Plugin і користувацькі шляхи завантаження все одно мають встановлюватися через `openclaw plugins install`. -Див. [Вирішення залежностей плагінів](/uk/plugins/dependency-resolution) щодо -життєвого циклу під час встановлення. +Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) для життєвого циклу +під час встановлення. -## Типи плагінів +## Типи Plugin -OpenClaw розпізнає два формати плагінів: +OpenClaw розпізнає два формати Plugin: | Формат | Як це працює | Приклади | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, npm-пакети спільноти | -| **Bundle** | Codex/Claude/Cursor-сумісна структура; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні Plugin, пакети npm спільноти | +| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Див. [Пакети плагінів](/uk/plugins/bundles) для деталей про пакети. +Обидва з’являються в `openclaw plugins list`. Див. [Пакети Plugin](/uk/plugins/bundles) для деталей пакетів. -Якщо ви пишете native-плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins) -та [Огляду Plugin SDK](/uk/plugins/sdk-overview). +Якщо ви пишете нативний Plugin, почніть із [Створення Plugin](/uk/plugins/building-plugins) +і [Огляд Plugin SDK](/uk/plugins/sdk-overview). ## Точки входу пакета -Npm-пакети native-плагінів мають оголошувати `openclaw.extensions` у `package.json`. -Кожен запис має залишатися всередині каталогу пакета й резолвитися у читабельний -runtime-файл або у вихідний TypeScript-файл з виведеним збудованим JavaScript -peer, наприклад `src/index.ts` до `dist/index.js`. +Пакети npm нативних Plugin мають оголошувати `openclaw.extensions` у `package.json`. +Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в читабельний +runtime-файл або в початковий файл TypeScript з виведеним зібраним JavaScript +парним файлом, наприклад `src/index.ts` до `dist/index.js`. Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за -тими самими шляхами, що й source-записи. Якщо `runtimeExtensions` присутній, він має містити -рівно один запис для кожного запису `extensions`. Невідповідні списки провалюють встановлення й -виявлення плагіна замість тихого fallback до source-шляхів. +тими самими шляхами, що й початкові записи. Коли `runtimeExtensions` присутній, він має містити +рівно один запис для кожного запису `extensions`. Невідповідні списки спричиняють помилку встановлення та +виявлення Plugin замість тихого повернення до початкових шляхів. ```json { @@ -149,21 +149,21 @@ peer, наприклад `src/index.ts` до `dist/index.js`. } ``` -## Офіційні плагіни +## Офіційні Plugin ### Npm-пакети, що належать OpenClaw, під час міграції -ClawHub — основний шлях розповсюдження для більшості плагінів. Поточні пакетовані -релізи OpenClaw уже містять багато офіційних плагінів, тому в нормальних установках вони не потребують -окремих npm-встановлень. Доки кожен плагін, що належить OpenClaw, не мігрує -до ClawHub, OpenClaw усе ще постачає деякі пакети плагінів `@openclaw/*` в +ClawHub є основним шляхом розповсюдження для більшості Plugin. Поточні упаковані +релізи OpenClaw уже містять багато офіційних Plugin, тож у звичайних налаштуваннях для них не потрібні +окремі npm-встановлення. Доки кожен Plugin, що належить OpenClaw, не +мігрує до ClawHub, OpenClaw все ще постачає деякі пакети Plugin `@openclaw/*` в npm для старіших/користувацьких встановлень і прямих npm-процесів. -Якщо npm повідомляє, що пакет плагіна `@openclaw/*` deprecated, ця версія пакета -походить зі старішої зовнішньої лінійки пакетів. Використовуйте bundled-плагін із +Якщо npm повідомляє, що пакет Plugin `@openclaw/*` є застарілим, ця версія пакета +походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований Plugin із поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. -| Плагін | Пакет | Документація | +| Plugin | Пакет | Документація | | --------------- | -------------------------- | ------------------------------------------ | | BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/uk/channels/bluebubbles) | | Discord | `@openclaw/discord` | [Discord](/uk/channels/discord) | @@ -179,7 +179,7 @@ npm для старіших/користувацьких встановлень | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачається з OpenClaw) +### Основні (постачаються з OpenClaw) @@ -190,12 +190,12 @@ npm для старіших/користувацьких встановлень `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — bundled-пошук пам'яті (за замовчуванням через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам'ять install-on-demand з auto-recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`) + + - `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`) - Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо OpenAI-сумісного - налаштування embeddings, прикладів Ollama, лімітів recall і усунення несправностей. + Див. [Memory LanceDB](/uk/plugins/memory-lancedb) для налаштування + OpenAI-сумісних embeddings, прикладів Ollama, обмежень пригадування та усунення несправностей. @@ -204,13 +204,13 @@ npm для старіших/користувацьких встановлень - - `browser` — bundled-плагін браузера для browser tool, `openclaw browser` CLI, `browser.request` gateway method, browser runtime і default browser control service (увімкнено за замовчуванням; вимкніть перед заміною) + - `browser` — вбудований Plugin браузера для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, runtime браузера та служби керування браузером за замовчуванням (увімкнено за замовчуванням; вимкніть перед заміною) - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням) -Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community). +Шукаєте сторонні Plugin? Див. [Plugin спільноти](/uk/plugins/community). ## Конфігурація @@ -231,49 +231,49 @@ npm для старіших/користувацьких встановлень | Поле | Опис | | ---------------- | --------------------------------------------------------- | | `enabled` | Головний перемикач (за замовчуванням: `true`) | -| `allow` | Allowlist плагінів (необов'язково) | -| `deny` | Denylist плагінів (необов'язково; deny має пріоритет) | -| `load.paths` | Додаткові файли/каталоги плагінів | +| `allow` | Allowlist Plugin (необов’язково) | +| `deny` | Denylist Plugin (необов’язково; deny має перевагу) | +| `load.paths` | Додаткові файли/каталоги Plugin | | `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі + конфігурація для кожного плагіна | +| `entries.\` | Перемикачі + конфігурація для окремих Plugin | -`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися -або надавати інструменти можуть лише перелічені плагіни, навіть якщо `tools.allow` містить `"*"` або конкретну -назву інструмента, що належить плагіну. Якщо allowlist інструментів посилається на інструменти плагінів, додайте id плагінів-власників +`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися або +відкривати інструменти можуть лише перелічені Plugin, навіть якщо `tools.allow` містить `"*"` або конкретну назву +інструмента, що належить Plugin. Якщо allowlist інструментів посилається на інструменти Plugin, додайте ідентифікатори Plugin-власників до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку форму. -Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими config -watch + in-process restart (типовий шлях `openclaw gateway`), цей -перезапуск зазвичай виконується автоматично за мить після запису конфігурації. -Немає підтримуваного шляху hot-reload для runtime-коду native-плагіна або lifecycle -hooks; перезапустіть процес Gateway, який обслуговує live-канал, перш ніж -очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, сервіси або -provider/runtime hooks почнуть виконуватися. +Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими +спостереженням за конфігурацією та перезапуском у процесі (стандартний шлях `openclaw gateway`), цей +перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. +Підтримуваного шляху гарячого перезавантаження для runtime-коду нативного Plugin або lifecycle +хуків немає; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж +очікувати виконання оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, служб або +provider/runtime хуків. -`openclaw plugins list` — це локальний snapshot реєстру/конфігурації плагінів. -Плагін зі статусом `enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють -плагіну брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway -перезапустився з тим самим кодом плагіна. У VPS/container-установках із -wrapper-процесами надсилайте перезапуски фактичному процесу `openclaw gateway run` -або використовуйте `openclaw gateway restart` проти запущеного Gateway. +`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. Позначений там як +`enabled` Plugin означає, що збережений реєстр і поточна конфігурація дозволяють +Plugin брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway +перезапустився з тим самим кодом Plugin. У VPS/container налаштуваннях з +процесами-обгортками надсилайте перезапуски фактичному процесу `openclaw gateway run` +або використовуйте `openclaw gateway restart` для запущеного Gateway. - - - **Disabled**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. - - **Missing**: конфігурація посилається на id плагіна, який discovery не знайшов. - - **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей плагін; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його й видаливши його config payload. + + - **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який виявлення не знайшло. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши його конфігураційне навантаження. -## Виявлення й пріоритет +## Виявлення та пріоритетність -OpenClaw сканує плагіни в такому порядку (перший збіг перемагає): +OpenClaw сканує Plugin у такому порядку (перша відповідність перемагає): `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують - назад на власні каталоги упакованих вбудованих Plugin OpenClaw, ігноруються; - виконайте `openclaw doctor --fix`, щоб прибрати ці застарілі псевдоніми. + назад на власні каталоги пакетних вбудованих Plugin OpenClaw, ігноруються; + виконайте `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. @@ -290,15 +290,15 @@ OpenClaw сканує плагіни в такому порядку (перши -Упаковані встановлення та образи Docker зазвичай визначають вбудовані Plugin з -скомпільованого дерева `dist/extensions`. Якщо каталог вихідного коду вбудованого Plugin -змонтовано bind mount поверх відповідного упакованого шляху вихідного коду, наприклад -`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований каталог вихідного коду -як накладку джерела вбудованого Plugin і виявляє його перед упакованим бандлом -`/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних циклів -супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. -Встановіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-бандли -навіть за наявності змонтованих накладок вихідного коду. +Пакетні встановлення та образи Docker зазвичай знаходять вбудовані Plugin у +скомпільованому дереві `dist/extensions`. Якщо вихідний каталог вбудованого Plugin +змонтовано поверх відповідного пакетного шляху до вихідного коду, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог +як накладання вбудованого вихідного коду й виявляє його перед пакетним бандлом +`/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних +циклів супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати пакетні dist-бандли +навіть за наявності монтувань накладання вихідного коду. ### Правила ввімкнення @@ -308,35 +308,35 @@ OpenClaw сканує плагіни в такому порядку (перши - Plugin, що походять із робочого простору, **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) - Вбудовані Plugin дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено - Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота -- Деякі вбудовані opt-in Plugin вмикаються автоматично, коли конфігурація називає - поверхню, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або - середовище виконання harness -- Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`; - повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете видалити застарілі id -- Маршрути Codex родини OpenAI зберігають окремі межі Plugin: - `openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin сервера застосунку Codex +- Деякі вбудовані Plugin з явним підключенням автоматично вмикаються, коли конфігурація називає + поверхню, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або runtime + тестового середовища +- Застаріла конфігурація Plugin зберігається, поки активне `plugins.enabled: false`; + повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете видалити застарілі ids +- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: + `openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin app-server Codex вибирається через `agentRuntime.id: "codex"` або застарілі посилання на моделі `codex/*` -## Усунення проблем із runtime hooks +## Усунення проблем runtime hooks -Якщо Plugin відображається у `plugins list`, але побічні ефекти або hooks -`register(api)` не виконуються в live-трафіку чату, спершу перевірте таке: +Якщо Plugin з’являється в `plugins list`, але побічні ефекти або hooks +`register(api)` не виконуються в живому чат-трафіку, спершу перевірте це: -- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні - URL Gateway, профіль, шлях конфігурації та процес саме ті, які ви редагуєте. -- Перезапустіть live Gateway після змін встановлення/конфігурації/коду Plugin. У wrapper +- Виконайте `openclaw gateway status --deep --require-rpc` і переконайтеся, що активні + URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте. +- Перезапустіть живий Gateway після встановлення Plugin або змін конфігурації/коду. У wrapper контейнерах PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використайте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hooks і - діагностику. Невбудовані hooks розмови, як-от `llm_input`, +- Використовуйте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hook і + діагностику. Невбудовані conversation hooks, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`, потребують `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до - розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі - створить відповідь асистента. -- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або - поверхні сесії/статусу Gateway, а під час налагодження payload провайдера запускайте +- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до розв’язання моделі + для ходів агента; `llm_output` виконується лише після того, як спроба моделі + створить вивід асистента. +- Для підтвердження ефективної моделі сеансу використовуйте `openclaw sessions` або + поверхні сеансів/статусу Gateway, а під час налагодження payload провайдера запускайте Gateway з `--raw-stream --raw-stream-path `. ### Дублювання володіння каналом або інструментом @@ -347,7 +347,7 @@ OpenClaw сканує плагіни в такому порядку (перши - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Це означає, що більше ніж один увімкнений Plugin намагається володіти тим самим каналом, +Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, встановлений поруч із вбудованим Plugin, який тепер надає той самий id каналу. @@ -356,7 +356,7 @@ OpenClaw сканує плагіни в такому порядку (перши - Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin і його походження. - Виконайте `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і - порівняйте `channels`, `channelConfigs`, `tools` та діагностику. + порівняйте `channels`, `channelConfigs`, `tools` і діагностику. - Виконайте `openclaw plugins registry --refresh` після встановлення або видалення пакетів Plugin, щоб збережені метадані відображали поточне встановлення. - Перезапустіть Gateway після змін встановлення, реєстру або конфігурації. @@ -366,16 +366,15 @@ OpenClaw сканує плагіни в такому порядку (перши - Якщо один Plugin навмисно замінює інший для того самого id каналу, бажаний Plugin має оголосити `channelConfigs..preferOver` з id Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). -- Якщо дублювання випадкове, вимкніть одну зі сторін за допомогою - `plugins.entries..enabled: false` або видаліть застаріле встановлення - Plugin. +- Якщо дублювання випадкове, вимкніть одну сторону через + `plugins.entries..enabled: false` або видаліть застаріле встановлення Plugin. - Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і - повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте - інструменти, що належать Plugin, щоб поверхня runtime була однозначною. + повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, + що належать Plugin, щоб runtime-поверхня була однозначною. ## Слоти Plugin (ексклюзивні категорії) -Деякі категорії є ексклюзивними (активною одночасно може бути лише одна): +Деякі категорії є ексклюзивними (одночасно активна лише одна): ```json5 { @@ -388,9 +387,9 @@ OpenClaw сканує плагіни в такому порядку (перши } ``` -| Слот | Що він контролює | Типове значення | -| --------------- | --------------------- | ------------------- | -| `memory` | Plugin активної пам’яті | `memory-core` | +| Слот | Що він контролює | За замовчуванням | +| --------------- | ----------------------- | ------------------ | +| `memory` | Plugin Active memory | `memory-core` | | `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | ## Довідник CLI @@ -442,79 +441,79 @@ openclaw plugins disable Вбудовані Plugin постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний -Plugin). Інші вбудовані Plugin усе ще потребують `openclaw plugins enable `. +Plugin). Інші вбудовані Plugin все ще потребують `openclaw plugins enable `. `--force` перезаписує наявний встановлений Plugin або hook pack на місці. Використовуйте `openclaw plugins update ` для звичайних оновлень відстежуваних npm -Plugin. Це не підтримується з `--link`, який повторно використовує шлях вихідного коду замість -копіювання поверх керованої цілі встановлення. +Plugin. Він не підтримується з `--link`, який повторно використовує шлях до вихідного коду замість +копіювання в керовану ціль встановлення. Коли `plugins.allow` уже задано, `openclaw plugins install` додає id встановленого Plugin до цього allowlist перед його ввімкненням. Якщо той самий id Plugin присутній у `plugins.deny`, встановлення видаляє цей застарілий запис deny, щоб явне встановлення можна було завантажити одразу після перезапуску. -OpenClaw зберігає сталий локальний реєстр Plugin як модель холодного читання для +OpenClaw зберігає локальний реєстр Plugin як холодну модель читання для інвентаризації Plugin, володіння внесками та планування запуску. Потоки встановлення, оновлення, видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану Plugin. Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у -верхньорівневому `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо +верхньорівневих `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо реєстр відсутній, застарілий або недійсний, `openclaw plugins registry ---refresh` перебудовує його подання маніфестів із записів встановлення, політики конфігурації та -метаданих маніфесту/пакета без завантаження runtime-модулів Plugin. +--refresh` перебудовує його представлення маніфестів із записів встановлення, політики конфігурації та +метаданих manifest/package без завантаження runtime-модулів Plugin. `openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета -назад із записом відстежуваного Plugin і записує нову специфікацію для майбутніх оновлень. -Передавання назви пакета без версії повертає точно закріплене встановлення назад до -типової лінії випусків реєстру. Якщо встановлений npm Plugin уже відповідає -розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення -без завантаження, перевстановлення або перезапису конфігурації. +npm package spec із dist-tag або точною версією розв’язує назву пакета +назад до відстежуваного запису Plugin і записує новий spec для майбутніх оновлень. +Передавання назви пакета без версії повертає точно pinned встановлення назад до +типової release line реєстру. Якщо встановлений npm Plugin уже відповідає +розв’язаній версії та записаній ідентичності артефакта, OpenClaw пропускає оновлення +без завантаження, повторного встановлення або переписування конфігурації. -`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, тому що -встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації. +`--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки +встановлення з marketplace зберігають метадані джерела marketplace замість npm spec. -`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних -спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення Plugin -і оновлення Plugin продовжуватися після вбудованих висновків `critical`, але все одно +`--dangerously-force-unsafe-install` — аварійне перевизначення для хибнопозитивних +спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановлення Plugin +і оновлення Plugin продовжуватися попри вбудовані findings рівня `critical`, але все одно не обходить блокування політики Plugin `before_install` або блокування через помилку сканування. -Сканування встановлення ігнорують типові тестові файли та каталоги, як-от `tests/`, -`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати упаковані тестові mocks; -оголошені runtime-точки входу Plugin усе одно скануються, навіть якщо вони використовують одну з +Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`, +`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати пакетні test mocks; +оголошені runtime-точки входу Plugin все одно скануються, навіть якщо вони використовують одну з цих назв. Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Встановлення -залежностей Skills, що підтримуються Gateway, натомість використовують відповідне перевизначення запиту +залежностей skill на основі Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком -завантаження/встановлення Skills із ClawHub. +завантаження/встановлення skill із ClawHub. Якщо Plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте панель ClawHub або виконайте `clawhub package rescan `, щоб попросити ClawHub перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій власній -машині; він не просить ClawHub повторно просканувати Plugin або зробити заблокований реліз +машині; він не просить ClawHub повторно сканувати Plugin або робити заблокований release публічним. -Сумісні бандли беруть участь у тому самому потоці списку/перевірки/ввімкнення/вимкнення -Plugin. Поточна підтримка runtime включає Skills бандлів, command-skills Claude, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті -`lspServers`, command-skills Cursor і сумісні каталоги hooks Codex. +Сумісні бандли беруть участь у тому самому потоці list/inspect/enable/disable +для Plugin. Поточна підтримка runtime включає bundle skills, Claude command-skills, +стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` і оголошені в маніфесті +`lspServers`, Cursor command-skills і сумісні каталоги hook Codex. -`openclaw plugins inspect ` також повідомляє про виявлені можливості бандлів, а також +`openclaw plugins inspect ` також повідомляє виявлені можливості бандла, а також підтримувані або непідтримувані записи серверів MCP і LSP для Plugin на основі бандлів. -Джерелами marketplace можуть бути відома Claude назва marketplace з -`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або -шлях `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL -репозиторію GitHub або git URL. Для віддалених marketplace записи Plugin мають -залишатися всередині клонованого репозиторію marketplace і використовувати лише -відносні джерела шляхів. +Джерелами маркетплейсу можуть бути відома назва маркетплейсу Claude з +`~/.claude/plugins/known_marketplaces.json`, локальний корінь маркетплейсу або +шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL +репозиторію GitHub або git URL. Для віддалених маркетплейсів записи Plugin +мають залишатися всередині клонованого репозиторію маркетплейсу та використовувати +лише відносні джерела шляхів. Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins). ## Огляд API Plugin -Нативні Plugin експортують об’єкт входу, який надає `register(api)`. Старіші -Plugin можуть досі використовувати `activate(api)` як застарілий псевдонім, але -нові Plugin мають використовувати `register`. +Нативні Plugin експортують об'єкт входу, який надає `register(api)`. Старіші +Plugin можуть усе ще використовувати `activate(api)` як застарілий псевдонім, але нові Plugin мають +використовувати `register`. ```typescript export default definePluginEntry({ @@ -534,75 +533,75 @@ export default definePluginEntry({ }); ``` -OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації -Plugin. Завантажувач досі повертається до `activate(api)` для старіших Plugin, -але вбудовані Plugin і нові зовнішні Plugin мають вважати `register` публічним -контрактом. +OpenClaw завантажує об'єкт входу та викликає `register(api)` під час +активації Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugin, +але вбудовані Plugin і нові зовнішні Plugin мають розглядати `register` як +публічний контракт. -`api.registrationMode` повідомляє Plugin, чому завантажується його вхід: +`api.registrationMode` повідомляє Plugin, чому його вхід завантажується: -| Режим | Значення | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація під час виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | -| `discovery` | Виявлення можливостей лише для читання. Реєструйте провайдери й метадані; довірений код входу Plugin може завантажуватися, але пропускайте активні побічні ефекти. | -| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. | -| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | -| `cli-metadata` | Лише збирання метаданих команд CLI. | +| Режим | Значення | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `full` | Активація в середовищі виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | +| `discovery` | Доступне лише для читання виявлення можливостей. Реєструйте провайдерів і метадані; довірений код входу Plugin може завантажуватися, але пропускайте активні побічні ефекти. | +| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | +| `cli-metadata` | Лише збирання метаданих команд CLI. | -Входи Plugin, які відкривають сокети, бази даних, фонових працівників або -довгоживучих клієнтів, мають захищати ці побічні ефекти через `api.registrationMode === "full"`. -Завантаження виявлення кешуються окремо від завантажень активації та не замінюють -поточний реєстр Gateway. Виявлення не активує, але не є вільним від імпорту: -OpenClaw може обчислити довірений вхід Plugin або модуль Plugin каналу, щоб -побудувати знімок. Тримайте верхній рівень модулів легким і без побічних ефектів, -а мережевих клієнтів, підпроцеси, слухачів, читання облікових даних і запуск -служб переміщуйте за шляхи повного середовища виконання. +Записи Plugin, які відкривають сокети, бази даних, фонові воркери або довготривалі +клієнти, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`. +Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють +поточний реєстр Gateway. Виявлення не є активаційним, але не є вільним від імпортів: +OpenClaw може виконати довірений вхід Plugin або модуль Plugin каналу, щоб побудувати +знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а мережеві +клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб переносьте +за шляхи повного середовища виконання. Поширені методи реєстрації: -| Метод | Що реєструє | -| --------------------------------------- | ----------------------------------- | -| `registerProvider` | Провайдер моделі (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | +| Метод | Що він реєструє | +| --------------------------------------- | --------------------------- | +| `registerProvider` | Провайдер моделі (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | | `registerSpeechProvider` | Перетворення тексту на мовлення / STT | -| `registerRealtimeTranscriptionProvider` | Потокове STT | -| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер Web fetch / scrape | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP endpoint | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Рушій контексту | -| `registerService` | Фонова служба | +| `registerRealtimeTranscriptionProvider` | Потокове STT | +| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Провайдер веботримання / скрейпінгу | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP-ендпоінт | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Рушій контексту | +| `registerService` | Фонова служба | Поведінка захисту хуків для типізованих хуків життєвого циклу: - `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` не виконує жодної дії й не скасовує попереднє блокування. +- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. - `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` не виконує жодної дії й не скасовує попереднє блокування. +- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. - `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` не виконує жодної дії й не скасовує попереднє скасування. +- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. -Нативний сервер застосунку Codex передає нативні для Codex події інструментів -назад у цю поверхню хуків. Plugin можуть блокувати нативні інструменти Codex -через `before_tool_call`, спостерігати результати через `after_tool_call` і -брати участь у схваленнях Codex `PermissionRequest`. Міст ще не переписує -аргументи нативних інструментів Codex. Точна межа підтримки середовища виконання -Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). +Нативний сервер застосунку Codex повертає події нативних інструментів Codex через міст +на цю поверхню хуків. Plugin можуть блокувати нативні інструменти Codex через `before_tool_call`, +спостерігати результати через `after_tool_call` та брати участь у схваленнях Codex +`PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. +Точна межа підтримки середовища виконання Codex описана в +[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). -## Пов’язане +## Пов'язане - [Створення Plugin](/uk/plugins/building-plugins) — створіть власний Plugin - [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor - [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту - [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin - [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Plugin спільноти](/uk/plugins/community) — списки сторонніх розробників +- [Спільнотні Plugin](/uk/plugins/community) — переліки сторонніх розробників