diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index a0253cbb5..d4c0402e4 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,43 +1,43 @@ --- read_when: - Встановлення або налаштування плагінів - - Розуміння правил виявлення та завантаження плагінів - - Робота з сумісними з Codex/Claude наборами плагінів + - Розуміння виявлення плагінів і правил завантаження + - Робота з наборами плагінів, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw +summary: Встановлення, налаштування та керування плагінами OpenClaw title: Плагіни x-i18n: - generated_at: "2026-04-20T16:49:55Z" + generated_at: "2026-04-23T00:37:18Z" model: gpt-5.4 provider: openai - source_hash: a34995fe8a27b7c96fb2abd9ef55bea38ea7ba2ff4e867977683e09f799e9e8f + source_hash: 120c96e5b80b6dc9f6c842f9d04ada595f32e21a311128ae053828747a793033 source_path: tools/plugin.md workflow: 15 --- # Плагіни -Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, +Плагіни розширюють OpenClaw новими можливостями: канали, провайдери моделей, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук -та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші -є **external** (публікуються спільнотою в npm). +тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші +є **external** (публікуються спільнотою на npm). -## Швидкий початок +## Швидкий старт - + ```bash openclaw plugins list ``` - + ```bash - # З npm + # From npm openclaw plugins install @openclaw/voice-call - # З локального каталогу або архіву + # From a local directory or archive openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -54,7 +54,7 @@ x-i18n: -Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню безпосередньо через чат, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub:@openclaw/voice-call @@ -62,52 +62,52 @@ x-i18n: /plugin enable voice-call ``` -Шлях установлення використовує той самий механізм визначення, що й CLI: локальний -шлях/архів, явний `clawhub:` або звичайна специфікація пакета (спочатку ClawHub, потім резервний варіант npm). +Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний +шлях/архів, явний `clawhub:` або специфікація пакета без префікса (спочатку ClawHub, потім резервний варіант через npm). -Якщо конфігурація недійсна, інсталяція зазвичай завершується без виконання змін і вказує вам на -`openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях +Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується з відмовою та +спрямовує вас до `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях перевстановлення вбудованого плагіна для плагінів, які підтримують `openclaw.install.allowInvalidConfigRecovery`. -Пакетні інсталяції OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання -для кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через -конфігурацію плагінів, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням, -під час запуску відновлюються лише оголошені залежності середовища виконання -цього плагіна перед його імпортом. External плагіни та власні шляхи завантаження -усе ще потрібно встановлювати через `openclaw plugins install`. +Пакетні встановлення OpenClaw не встановлюють заздалегідь усе дерево залежностей +середовища виконання для кожного вбудованого плагіна. Коли вбудований плагін OpenClaw активний через +конфігурацію плагіна, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням, +під час запуску відновлюються лише оголошені залежності середовища виконання цього плагіна перед його імпортом. +Зовнішні плагіни та власні шляхи завантаження, як і раніше, потрібно встановлювати через +`openclaw plugins install`. ## Типи плагінів OpenClaw розпізнає два формати плагінів: -| Формат | Як це працює | Приклади | -| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, пакети npm від спільноти | -| **Bundle** | Макет, сумісний з Codex/Claude/Cursor; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| Формат | Як це працює | Приклади | +| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ | +| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в процесі | Офіційні плагіни, пакети npm від спільноти | +| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Докладніше про набори дивіться в [Набори плагінів](/uk/plugins/bundles). +Обидва відображаються в `openclaw plugins list`. Докладніше про набори див. у [Набори плагінів](/uk/plugins/bundles). -Якщо ви пишете Native плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins) -та [Огляд Plugin SDK](/uk/plugins/sdk-overview). +Якщо ви пишете native-плагін, почніть з [Створення плагінів](/uk/plugins/building-plugins) +і [Огляду Plugin SDK](/uk/plugins/sdk-overview). ## Офіційні плагіни ### Доступні для встановлення (npm) -| Плагін | Пакет | Документація | -| --------------- | --------------------- | ------------------------------------ | -| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | +| Плагін | Пакет | Документація | +| --------------- | ---------------------- | ----------------------------------- | +| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | +| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачаються разом з OpenClaw) +### Core (постачаються з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -116,16 +116,16 @@ OpenClaw розпізнає два формати плагінів: - - `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам’ять із встановленням на вимогу з автоматичним відновленням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) + - `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять із встановленням на вимогу, автоматичним відновленням і захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) - + `elevenlabs`, `microsoft` - - `browser` — вбудований browser Plugin для інструмента browser, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання browser і служби керування browser за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною) + - `browser` — вбудований browser Plugin для інструмента browser, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання browser і стандартного сервісу керування browser (увімкнений за замовчуванням; вимкніть його перед заміною) - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням) @@ -155,13 +155,13 @@ OpenClaw розпізнає два формати плагінів: | `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) | | `load.paths` | Додаткові файли/каталоги плагінів | | `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі та конфігурація для окремого плагіна | +| `entries.\` | Перемикачі й конфігурація для окремого плагіна | -Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з відстеженням -конфігурації та увімкненим перезапуском у межах процесу (типовий шлях `openclaw gateway`), -цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію. +Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з +відстеженням конфігурації та увімкненим перезапуском у процесі (стандартний шлях `openclaw gateway`), +цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. - + - **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення. - **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. @@ -169,7 +169,7 @@ OpenClaw розпізнає два формати плагінів: ## Виявлення та пріоритет -OpenClaw сканує плагіни в такому порядку (перше знайдене збігом і використовується): +OpenClaw сканує плагіни в такому порядку (перше знайдене збігання перемагає): @@ -185,8 +185,8 @@ OpenClaw сканує плагіни в такому порядку (перше - Постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). - Інші потребують явного ввімкнення. + Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). + Для інших потрібне явне ввімкнення. @@ -195,56 +195,56 @@ OpenClaw сканує плагіни в такому порядку (перше - `plugins.enabled: false` вимикає всі плагіни - `plugins.deny` завжди має пріоритет над allow - `plugins.entries.\.enabled: false` вимикає цей плагін -- Плагіни з джерелом із робочого простору **типово вимкнені** (їх потрібно явно ввімкнути) -- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено +- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Вбудовані плагіни дотримуються вбудованого набору «увімкнено за замовчуванням», якщо це не перевизначено - Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота ## Слоти плагінів (ексклюзивні категорії) -Деякі категорії є ексклюзивними (одночасно може бути активним лише один): +Деякі категорії є ексклюзивними (одночасно активний лише один): ```json5 { plugins: { slots: { - memory: "memory-core", // або "none", щоб вимкнути - contextEngine: "legacy", // або ідентифікатор плагіна + memory: "memory-core", // or "none" to disable + contextEngine: "legacy", // or a plugin id }, }, } ``` -| Слот | Що він керує | Типове значення | -| --------------- | -------------------------- | ------------------- | -| `memory` | Active Memory плагін | `memory-core` | -| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | +| Слот | Що він контролює | Типове значення | +| --------------- | ------------------------ | ------------------ | +| `memory` | Active Memory Plugin | `memory-core` | +| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | ## Довідка CLI ```bash -openclaw plugins list # стислий перелік +openclaw plugins list # компактний перелік openclaw plugins list --enabled # лише завантажені плагіни -openclaw plugins list --verbose # рядки з детальною інформацією про кожен плагін -openclaw plugins list --json # машиночитаний перелік -openclaw plugins inspect # детальна інформація -openclaw plugins inspect --json # машиночитаний формат +openclaw plugins list --verbose # рядки з подробицями для кожного плагіна +openclaw plugins list --json # машинозчитуваний перелік +openclaw plugins inspect # докладна інформація +openclaw plugins inspect --json # машинозчитуваний формат openclaw plugins inspect --all # таблиця для всього набору openclaw plugins info # псевдонім inspect openclaw plugins doctor # діагностика -openclaw plugins install # установлення (спочатку ClawHub, потім npm) -openclaw plugins install clawhub: # установлення лише з ClawHub +openclaw plugins install # встановлення (спочатку ClawHub, потім npm) +openclaw plugins install clawhub: # встановлення лише з ClawHub openclaw plugins install --force # перезаписати наявне встановлення -openclaw plugins install # установлення з локального шляху -openclaw plugins install -l # зв’язати (без копіювання) для розробки +openclaw plugins install # встановлення з локального шляху +openclaw plugins install -l # підключення (без копіювання) для розробки openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// openclaw plugins install --pin # записати точну розв’язану специфікацію npm openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # оновити один плагін -openclaw plugins update --dangerously-force-unsafe-install -openclaw plugins update --all # оновити все -openclaw plugins uninstall # видалити записи конфігурації/установлення +openclaw plugins update # оновити один плагін +openclaw plugins update --dangerously-force-unsafe-install +openclaw plugins update --all # оновити всі +openclaw plugins uninstall # видалити записи конфігурації/встановлення openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -253,45 +253,55 @@ openclaw plugins enable openclaw plugins disable ``` -Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, -вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований -browser Plugin). Інші вбудовані плагіни все одно потребують `openclaw plugins enable `. +Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад, +вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований browser +Plugin). Інші вбудовані плагіни все одно потрібно вмикати через `openclaw plugins enable `. -`--force` перезаписує наявний установлений плагін або пакет хуків на місці. -Він не підтримується разом із `--link`, який повторно використовує вихідний шлях -замість копіювання в керовану ціль інсталяції. +`--force` перезаписує наявний встановлений плагін або набір хуків на місці. Для +звичайних оновлень відстежуваних npm-плагінів використовуйте +`openclaw plugins update `. Цей параметр не підтримується разом із `--link`, який повторно використовує вихідний шлях +замість копіювання в керовану ціль встановлення. + +`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання +специфікації npm-пакета з dist-tag або точною версією перетворює назву пакета +назад на запис відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень. +Передавання назви пакета без версії переводить точно закріплене встановлення назад на +стандартну лінію випусків реєстру. Якщо встановлений npm-плагін уже відповідає +розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення +без завантаження, перевстановлення чи перезапису конфігурації. `--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки -установлення з marketplace зберігають метадані джерела marketplace, а не специфікацію npm. +встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm. -`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних -спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє інсталяції та оновлення -плагінів продовжуватися попри вбудовані результати рівня `critical`, але все одно -не обходить блокування політики плагіна `before_install` або блокування через помилку сканування. +`--dangerously-force-unsafe-install` — це аварійний обхідний прапорець для хибних +спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє встановленню та оновленню плагінів +продовжуватися попри вбудовані результати `critical`, але все одно +не обходить блокування політики `before_install` плагіна або блокування через збій сканування. -Цей прапорець CLI застосовується лише до потоків інсталяції/оновлення плагінів. Установлення залежностей -Skills через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/установлення Skills через ClawHub. +Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей +Skills через Gateway натомість використовують відповідний параметр запиту +`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. -Сумісні набори беруть участь у тих самих потоках list/inspect/enable/disable для плагінів. +Сумісні набори беруть участь у тому самому потоці list/inspect/enable/disable для плагінів. Поточна підтримка середовища виконання включає bundle Skills, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті -`lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. +`lspServers`, command-skills Cursor та сумісні каталоги хуків Codex. `openclaw plugins inspect ` також повідомляє про виявлені можливості набору, а також підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі наборів. -Джерелами marketplace можуть бути відома назва marketplace Claude з -`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях -`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або URL git. Для віддалених marketplace записи плагінів мають залишатися всередині -клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. +Джерела marketplace можуть бути відомою назвою marketplace Claude з +`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або шляхом до +`marketplace.json`, скороченим записом GitHub на кшталт `owner/repo`, URL репозиторію GitHub +або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах +клонованого репозиторію marketplace і використовувати лише відносні шляхи до джерел. -Повні відомості дивіться в [довідці CLI `openclaw plugins`](/cli/plugins). +Повні відомості див. у [довідці CLI `openclaw plugins`](/cli/plugins). ## Огляд API плагінів -Native плагіни експортують об’єкт entry, який надає `register(api)`. Старіші -плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але для нових плагінів слід +Native-плагіни експортують об’єкт entry, який надає `register(api)`. Старіші +плагіни можуть і далі використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають використовувати `register`. ```typescript @@ -313,48 +323,48 @@ export default definePluginEntry({ ``` OpenClaw завантажує об’єкт entry і викликає `register(api)` під час -активації плагіна. Завантажувач і далі використовує `activate(api)` як резервний варіант для старіших плагінів, -але вбудовані плагіни та нові external плагіни повинні розглядати `register` як +активації плагіна. Завантажувач і далі повертається до `activate(api)` для старіших плагінів, +але вбудовані плагіни та нові зовнішні плагіни мають розглядати `register` як публічний контракт. Поширені методи реєстрації: | Метод | Що він реєструє | | --------------------------------------- | -------------------------- | -| `registerProvider` | Постачальник моделей (LLM) | +| `registerProvider` | Провайдер моделі (LLM) | | `registerChannel` | Канал чату | | `registerTool` | Інструмент агента | | `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Перетворення тексту на мовлення / STT | +| `registerSpeechProvider` | Text-to-speech / STT | | `registerRealtimeTranscriptionProvider` | Потоковий STT | | `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | | `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | | `registerImageGenerationProvider` | Генерація зображень | | `registerMusicGenerationProvider` | Генерація музики | | `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Постачальник отримання / збирання даних з вебу | +| `registerWebFetchProvider` | Провайдер web fetch / scrape | | `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP endpoint | +| `registerHttpRoute` | HTTP-ендпойнт | | `registerCommand` / `registerCli` | Команди CLI | | `registerContextEngine` | Рушій контексту | -| `registerService` | Фонова служба | +| `registerService` | Фоновий сервіс | Поведінка guard-хуків для типізованих хуків життєвого циклу: - `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 }` не має ефекту й не скасовує попереднє скасування. -Повну типізовану поведінку хуків дивіться в [Огляд SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Повну інформацію про поведінку типізованих хуків див. в [Огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане - [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін - [Набори плагінів](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor - [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагін +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін - [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Плагіни спільноти](/uk/plugins/community) — сторонні добірки +- [Плагіни спільноти](/uk/plugins/community) — списки сторонніх плагінів