chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4fad114bcf
commit
b3dc3209c0
@ -1,27 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Встановлення або налаштування плагінів
|
||||
- Встановлення або налаштування Plugin
|
||||
- Розуміння правил виявлення та завантаження Plugin
|
||||
- Робота з пакетами Plugin, сумісними з Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Встановлення, налаштування та керування плагінами OpenClaw
|
||||
summary: Установлення, налаштування та керування Plugin OpenClaw
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T03:16:55Z"
|
||||
generated_at: "2026-05-02T11:23:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c9378ef4a6aef26949148702f2f6d8537811869511e8830ae5c3d560ff06d98b
|
||||
source_hash: 97ec11a601445fa948d5639a6d461bcf3846a3c70d3eb304a66243a3d8ce810a
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей,
|
||||
оболонки агентів, інструменти, skills, мовлення, транскрипція в реальному часі,
|
||||
голос у реальному часі, розуміння медіа, генерація зображень, генерація відео,
|
||||
отримання вебданих, вебпошук тощо. Деякі plugins є **основними** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх plugins публікуються й виявляються через
|
||||
[ClawHub](/uk/tools/clawhub). Npm і надалі підтримується для прямих встановлень і для
|
||||
тимчасового набору пакетів plugins, що належать OpenClaw, доки ця міграція завершується.
|
||||
Плагіни розширюють OpenClaw новими можливостями: каналами, постачальниками моделей,
|
||||
агентськими середовищами, інструментами, Skills, мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, отриманням вебданих, вебпошуком тощо. Деякі плагіни є **основними** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх плагінів публікуються та виявляються через
|
||||
[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для
|
||||
тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -32,7 +30,7 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Установіть plugin">
|
||||
<Step title="Встановіть плагін">
|
||||
```bash
|
||||
# Search ClawHub plugins
|
||||
openclaw plugins search "calendar"
|
||||
@ -62,7 +60,7 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте plugin">
|
||||
<Step title="Перевірте плагін">
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
|
||||
@ -71,13 +69,13 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
```
|
||||
|
||||
Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, сервіси, методи gateway,
|
||||
hooks або CLI-команди, що належать plugin. Звичайний `inspect` — це холодна
|
||||
перевірка маніфесту/реєстру, яка навмисно уникає імпорту runtime plugin.
|
||||
хуки або команди CLI, якими володіє плагін. Звичайний `inspect` є холодною
|
||||
перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime плагіна.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо ви віддаєте перевагу керуванню, природному для чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:<package>
|
||||
@ -85,74 +83,74 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний
|
||||
Шлях встановлення використовує той самий розпізнавач, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>`, явний `git:<repo>` або проста специфікація пакета
|
||||
(спершу ClawHub, потім резервний npm).
|
||||
(спочатку ClawHub, потім резервний npm).
|
||||
|
||||
Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується помилкою й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях повторного встановлення bundled-plugin
|
||||
для plugins, які явно вмикають
|
||||
Якщо конфігурація недійсна, встановлення зазвичай аварійно завершується закрито й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-plugin
|
||||
для плагінів, які явно вмикають
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
Під час запуску Gateway недійсна конфігурація одного plugin ізолюється до цього plugin:
|
||||
запуск записує в лог проблему `plugins.entries.<id>.config`, пропускає цей plugin під час
|
||||
завантаження й залишає інші plugins і канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити погану конфігурацію plugin у карантин, вимкнувши цей запис plugin і видаливши
|
||||
Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється до цього плагіна:
|
||||
запуск записує в журнал проблему `plugins.entries.<id>.config`, пропускає цей плагін під час
|
||||
завантаження та залишає інші плагіни й канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити погану конфігурацію плагіна в карантин, вимкнувши цей запис плагіна та видаливши
|
||||
його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на plugin, який більше не можна виявити, але той самий
|
||||
застарілий ідентифікатор plugin залишається в конфігурації plugin або записах встановлення, запуск Gateway
|
||||
записує попередження й пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/plugin; невідомі
|
||||
ключі каналів без доказів застарілого plugin і надалі не проходять валідацію, тож помилки введення залишаються
|
||||
Коли конфігурація каналу посилається на плагін, який більше не виявляється, але той самий
|
||||
застарілий ідентифікатор плагіна залишається в конфігурації плагінів або записах встановлення, запуск Gateway
|
||||
записує попередження в журнал і пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі
|
||||
ключі каналів без доказів застарілого плагіна все одно провалюють валідацію, щоб друкарські помилки лишалися
|
||||
видимими.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на plugin вважаються інертними:
|
||||
запуск Gateway пропускає роботу з виявлення/завантаження plugin, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію plugin замість автоматичного видалення. Увімкніть plugins повторно перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори plugin.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються інертними:
|
||||
запуск Gateway пропускає роботу з виявлення/завантаження плагінів, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію плагінів замість автоматичного видалення. Повторно ввімкніть плагіни перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори плагінів.
|
||||
|
||||
Встановлення залежностей plugin відбувається лише під час явних потоків встановлення/оновлення або
|
||||
ремонту doctor. Запуск Gateway, перезавантаження конфігурації та runtime-перевірка не
|
||||
запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні plugins уже мають
|
||||
мати встановлені залежності, тоді як npm, git і ClawHub plugins
|
||||
встановлюються в керованих коренях plugins OpenClaw. Залежності npm можуть бути підняті
|
||||
в межах керованого npm-кореня OpenClaw; встановлення/оновлення сканує цей керований корінь перед
|
||||
довірою, а видалення прибирає npm-керовані пакети через npm. Зовнішні plugins
|
||||
і користувацькі шляхи завантаження все одно мають встановлюватися через `openclaw plugins install`.
|
||||
Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо життєвого циклу
|
||||
під час встановлення.
|
||||
Встановлення залежностей плагінів відбувається лише під час явних потоків install/update або
|
||||
відновлення doctor. Запуск Gateway, перезавантаження конфігурації та перевірка runtime не
|
||||
запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні плагіни вже повинні
|
||||
мати встановлені залежності, тоді як плагіни npm, git і ClawHub встановлюються
|
||||
в керованих коренях плагінів OpenClaw. Залежності npm можуть підійматися
|
||||
всередині керованого npm-кореня OpenClaw; install/update сканує цей керований корінь перед
|
||||
довірою, а uninstall видаляє npm-керовані пакети через npm. Зовнішні плагіни
|
||||
та користувацькі шляхи завантаження все одно потрібно встановлювати через `openclaw plugins install`.
|
||||
Див. [Розв’язання залежностей плагінів](/uk/plugins/dependency-resolution) щодо
|
||||
життєвого циклу під час встановлення.
|
||||
|
||||
Вихідні checkout-и є pnpm workspaces. Якщо ви клонуєте OpenClaw, щоб працювати над bundled
|
||||
plugins, запустіть `pnpm install`; після цього OpenClaw завантажує bundled plugins з
|
||||
`extensions/<id>`, тож зміни й локальні залежності пакета використовуються напряму.
|
||||
Звичайні кореневі встановлення npm призначені для packaged OpenClaw, а не для розробки
|
||||
Вихідні checkout-и є pnpm workspace-ами. Якщо ви клонуєте OpenClaw, щоб працювати над bundled
|
||||
плагінами, запустіть `pnpm install`; після цього OpenClaw завантажує bundled плагіни з
|
||||
`extensions/<id>`, тож зміни й пакетно-локальні залежності використовуються безпосередньо.
|
||||
Звичайні кореневі встановлення npm призначені для пакетованого OpenClaw, а не для розробки
|
||||
з source checkout.
|
||||
|
||||
## Типи Plugin
|
||||
## Типи плагінів
|
||||
|
||||
OpenClaw розпізнає два формати plugin:
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні plugins, пакети спільноти npm |
|
||||
| **Bundle** | Макет, сумісний із Codex/Claude/Cursor; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, спільнотні npm-пакети |
|
||||
| **Пакет** | Codex/Claude/Cursor-сумісна структура; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для подробиць про bundle.
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Пакети плагінів](/uk/plugins/bundles) для деталей про пакети.
|
||||
|
||||
Якщо ви пишете native plugin, почніть із [Створення Plugins](/uk/plugins/building-plugins)
|
||||
та [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете нативний плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins)
|
||||
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Точки входу пакета
|
||||
|
||||
Пакети npm із native plugin мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в доступний для читання
|
||||
runtime-файл або у вихідний файл TypeScript з виведеним збудованим JavaScript
|
||||
відповідником, наприклад від `src/index.ts` до `dist/index.js`.
|
||||
Нативні npm-пакети плагінів мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині каталогу пакета та розв’язуватися в читабельний
|
||||
runtime-файл або у TypeScript-файл вихідного коду з виведеним побудованим JavaScript
|
||||
відповідником, наприклад `src/index.ts` до `dist/index.js`.
|
||||
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за
|
||||
тими самими шляхами, що й вихідні записи. Коли `runtimeExtensions` присутній, він має містити
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки спричиняють помилку встановлення й
|
||||
виявлення plugin замість тихого повернення до вихідних шляхів. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його збудованого
|
||||
JavaScript-відповідника; цей файл обов’язковий, якщо його оголошено.
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки провалюють встановлення та
|
||||
виявлення плагіна замість тихого повернення до шляхів вихідного коду. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його побудованого
|
||||
JavaScript-відповідника; цей файл є обов’язковим, коли оголошений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -164,21 +162,21 @@ JavaScript-відповідника; цей файл обов’язковий,
|
||||
}
|
||||
```
|
||||
|
||||
## Офіційні plugins
|
||||
## Офіційні плагіни
|
||||
|
||||
### Пакети npm, що належать OpenClaw, під час міграції
|
||||
### Npm-пакети, що належать OpenClaw, під час міграції
|
||||
|
||||
ClawHub є основним шляхом розповсюдження для більшості plugins. Поточні packaged
|
||||
релізи OpenClaw уже містять багато офіційних plugins, тому вони не потребують
|
||||
окремих встановлень npm у звичайних налаштуваннях. Доки кожен plugin, що належить OpenClaw, не
|
||||
мігрував до ClawHub, OpenClaw усе ще постачає деякі пакети plugins `@openclaw/*` на
|
||||
ClawHub є основним шляхом дистрибуції для більшості плагінів. Поточні пакетовані
|
||||
релізи OpenClaw уже містять багато офіційних плагінів, тому вони не потребують
|
||||
окремих встановлень npm у звичайних налаштуваннях. Доки кожен плагін, що належить OpenClaw, не
|
||||
мігрує до ClawHub, OpenClaw все ще постачає деякі пакети плагінів `@openclaw/*` на
|
||||
npm для старіших/користувацьких встановлень і прямих npm-процесів.
|
||||
|
||||
Якщо npm повідомляє, що пакет plugin `@openclaw/*` застарілий, ця версія пакета
|
||||
належить до старішої зовнішньої лінійки пакетів. Використовуйте bundled plugin із
|
||||
поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший пакет npm.
|
||||
Якщо npm повідомляє, що пакет плагіна `@openclaw/*` застарів, ця версія пакета
|
||||
походить зі старішої зовнішньої гілки пакетів. Використовуйте bundled плагін із
|
||||
поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
| Plugin | Пакет | Документація |
|
||||
| Плагін | Пакет | Документація |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/uk/channels/bluebubbles) |
|
||||
| Discord | `@openclaw/discord` | [Discord](/uk/channels/discord) |
|
||||
@ -194,10 +192,10 @@ npm для старіших/користувацьких встановлень
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
|
||||
### Core (постачається з OpenClaw)
|
||||
### Основні (постачаються з OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнено за замовчуванням)">
|
||||
<Accordion title="Постачальники моделей (увімкнені за замовчуванням)">
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
@ -205,27 +203,27 @@ npm для старіших/користувацьких встановлень
|
||||
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory plugins">
|
||||
- `memory-core` — bundled memory search (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довгострокова пам’ять на базі LanceDB з автоматичним recall/capture (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — bundled пошук пам’яті (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо OpenAI-сумісного
|
||||
налаштування embeddings, прикладів Ollama, обмежень recall і усунення несправностей.
|
||||
налаштування embedding, прикладів Ollama, лімітів recall і усунення несправностей.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнено за замовчуванням)">
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — bundled browser plugin для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і типового сервісу керування browser (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням)
|
||||
- `browser` — bundled плагін браузера для інструмента браузера, CLI `openclaw browser`, gateway-методу `browser.request`, runtime браузера та стандартного сервісу керування браузером (увімкнений за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні plugins? Див. [Community Plugins](/uk/plugins/community).
|
||||
Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -243,121 +241,120 @@ npm для старіших/користувацьких встановлень
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Опис |
|
||||
| Поле | Опис |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Головний перемикач (типово: `true`) |
|
||||
| `allow` | Allowlist plugins (необов’язково) |
|
||||
| `deny` | Denylist plugins (необов’язково; deny має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги plugins |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `allow` | Список дозволених плагінів (необов’язково) |
|
||||
| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги плагінів |
|
||||
| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі й конфігурація для окремого plugin |
|
||||
| `entries.\<id\>` | Перемикачі + конфігурація для окремого плагіна |
|
||||
|
||||
`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися
|
||||
або надавати інструменти можуть лише перелічені plugins, навіть якщо `tools.allow` містить `"*"` або конкретну назву
|
||||
інструмента, що належить plugin. Якщо allowlist інструментів посилається на інструменти plugin, додайте ідентифікатори plugins-власників
|
||||
або відкривати інструменти можуть лише перелічені плагіни, навіть якщо `tools.allow` містить `"*"` або конкретну назву інструмента, яким володіє плагін. Якщо allowlist інструментів посилається на інструменти плагінів, додайте ідентифікатори плагінів-власників
|
||||
до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку
|
||||
структуру.
|
||||
форму.
|
||||
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з config
|
||||
watch + увімкненим in-process restart (типовий шлях `openclaw gateway`), цей
|
||||
Зміни конфігурації **вимагають перезапуску gateway**. Якщо Gateway працює з увімкненим спостереженням за конфігурацією
|
||||
та перезапуском у процесі (стандартний шлях `openclaw gateway`), цей
|
||||
перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
|
||||
Підтримуваного шляху hot-reload для runtime-коду native plugin або lifecycle
|
||||
hooks немає; перезапустіть процес Gateway, який обслуговує live-канал, перш ніж
|
||||
очікувати, що оновлений код `register(api)`, hooks `api.on(...)`, інструменти, сервіси або
|
||||
provider/runtime hooks почнуть виконуватися.
|
||||
Підтримуваного шляху hot-reload для runtime-коду нативного плагіна або lifecycle
|
||||
хуків немає; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж
|
||||
очікувати виконання оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, сервісів або
|
||||
provider/runtime хуків.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Плагін зі станом
|
||||
`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють
|
||||
плагіну брати участь. Це не доводить, що вже запущений віддалений дочірній процес
|
||||
Gateway перезапустився з тим самим кодом плагіна. У налаштуваннях VPS/контейнерів
|
||||
із процесами-обгортками надсилайте перезапуски фактичному процесу
|
||||
`openclaw gateway run` або використовуйте `openclaw gateway restart` для запущеного Gateway.
|
||||
`openclaw plugins list` — це локальний знімок реєстру/config Plugin. Увімкнений там Plugin
|
||||
`enabled` означає, що збережений реєстр і поточний config дозволяють
|
||||
Plugin брати участь. Це не доводить, що вже запущений віддалений дочірній процес
|
||||
Gateway перезапустився з тим самим кодом Plugin. У налаштуваннях VPS/container із
|
||||
процесами-обгортками надсилайте перезапуски фактичному процесу `openclaw gateway run`
|
||||
або використовуйте `openclaw gateway restart` для запущеного Gateway.
|
||||
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення вимкнули його. Конфігурацію збережено.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який виявлення не знайшло.
|
||||
- **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей плагін; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та видаливши його конфігураційне навантаження.
|
||||
<Accordion title="Стани Plugin: вимкнений vs відсутній vs недійсний">
|
||||
- **Вимкнений**: Plugin існує, але правила ввімкнення вимкнули його. Config збережено.
|
||||
- **Відсутній**: config посилається на id Plugin, який виявлення не знайшло.
|
||||
- **Недійсний**: Plugin існує, але його config не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши payload його config.
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Виявлення та пріоритет
|
||||
|
||||
OpenClaw шукає плагіни в такому порядку (перший збіг перемагає):
|
||||
OpenClaw сканує Plugins у такому порядку (перший збіг перемагає):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи конфігурації">
|
||||
<Step title="Шляхи config">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують
|
||||
назад на власні пакетовані каталоги вбудованих плагінів OpenClaw, ігноруються;
|
||||
запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми.
|
||||
назад на власні packaged каталоги bundled plugins OpenClaw, ігноруються;
|
||||
виконайте `openclaw doctor --fix`, щоб видалити ці застарілі alias.
|
||||
</Step>
|
||||
|
||||
<Step title="Плагіни робочої області">
|
||||
<Step title="Plugins робочої області">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` і `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Глобальні плагіни">
|
||||
<Step title="Глобальні Plugins">
|
||||
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Вбудовані плагіни">
|
||||
Постачаються з OpenClaw. Багато з них увімкнені типово (постачальники моделей, мовлення).
|
||||
<Step title="Bundled plugins">
|
||||
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Пакетовані встановлення й Docker-образи зазвичай розв’язують вбудовані плагіни з
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог вбудованого плагіна
|
||||
змонтовано bind mount поверх відповідного пакетованого вихідного шляху, наприклад
|
||||
Packaged installs та Docker images зазвичай знаходять bundled plugins із
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог bundled plugin
|
||||
bind-mounted поверх відповідного packaged source path, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог
|
||||
як вихідне накладання вбудованого плагіна й виявляє його перед пакетованим
|
||||
пакетом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних
|
||||
циклів супровідників без перемикання кожного вбудованого плагіна назад на вихідний
|
||||
код TypeScript. Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово
|
||||
використовувати пакетовані dist-пакети навіть за наявності змонтованих вихідних накладань.
|
||||
як bundled source overlay і виявляє його перед packaged bundle
|
||||
`/app/dist/extensions/synology-chat`. Це зберігає працездатність container loops
|
||||
для maintainer без перемикання кожного bundled plugin назад на TypeScript source.
|
||||
Задайте `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати packaged dist bundles,
|
||||
навіть коли присутні source overlay mounts.
|
||||
|
||||
### Правила ввімкнення
|
||||
|
||||
- `plugins.enabled: false` вимикає всі плагіни й пропускає роботу з виявлення/завантаження плагінів
|
||||
- `plugins.enabled: false` вимикає всі Plugins і пропускає роботу з виявлення/завантаження Plugin
|
||||
- `plugins.deny` завжди має перевагу над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей плагін
|
||||
- Плагіни з робочої області **вимкнені типово** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані плагіни дотримуються вбудованого набору типово ввімкнених, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота
|
||||
- Деякі вбудовані opt-in плагіни вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить плагіну, як-от посилання на модель постачальника, конфігурацію каналу або
|
||||
runtime harness
|
||||
- Застаріла конфігурація плагіна зберігається, поки активне `plugins.enabled: false`;
|
||||
повторно ввімкніть плагіни перед запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори
|
||||
- Маршрути Codex родини OpenAI зберігають окремі межі плагінів:
|
||||
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін сервера застосунку Codex
|
||||
вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
посилання на моделі `codex/*`
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей Plugin
|
||||
- Plugins із робочої області **вимкнені за замовчуванням** (мають бути явно ввімкнені)
|
||||
- Bundled plugins дотримуються вбудованого набору default-on, якщо його не перевизначено
|
||||
- Exclusive slots можуть примусово ввімкнути вибраний Plugin для цього slot
|
||||
- Деякі bundled opt-in Plugins вмикаються автоматично, коли config називає
|
||||
поверхню, що належить Plugin, наприклад provider model ref, channel config або harness
|
||||
runtime
|
||||
- Застарілий config Plugin зберігається, поки активне `plugins.enabled: false`;
|
||||
повторно ввімкніть Plugins перед запуском очищення doctor, якщо хочете видалити застарілі ids
|
||||
- Маршрути сімейства OpenAI Codex зберігають окремі межі Plugin:
|
||||
`openai-codex/*` належить OpenAI Plugin, тоді як bundled Codex
|
||||
app-server Plugin вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
refs моделей `codex/*`
|
||||
|
||||
## Усунення несправностей runtime-хуків
|
||||
## Усунення проблем із runtime hooks
|
||||
|
||||
Якщо плагін з’являється в `plugins list`, але побічні ефекти або хуки
|
||||
`register(api)` не виконуються в живому чат-трафіку, спершу перевірте таке:
|
||||
Якщо Plugin відображається в `plugins list`, але побічні ефекти `register(api)` або hooks
|
||||
не виконуються в живому chat traffic, спершу перевірте таке:
|
||||
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте.
|
||||
- Перезапустіть живий Gateway після змін встановлення/конфігурації/коду плагіна. У контейнерах
|
||||
з обгортками PID 1 може бути лише supervisor; перезапустіть або надішліть сигнал дочірньому
|
||||
- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, profile, config path і process саме ті, які ви редагуєте.
|
||||
- Перезапустіть live Gateway після змін install/config/code Plugin. У wrapper
|
||||
containers PID 1 може бути лише supervisor; перезапустіть або надішліть signal дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використайте `openclaw plugins inspect <id> --runtime --json`, щоб підтвердити реєстрації хуків і
|
||||
діагностику. Невбудовані хуки розмов, як-от `llm_input`,
|
||||
- Використайте `openclaw plugins inspect <id> --runtime --json`, щоб підтвердити реєстрації hooks і
|
||||
diagnostics. Non-bundled conversation hooks, як-от `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` і `agent_end`, потребують
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується перед розв’язанням моделі
|
||||
для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить вивід асистента.
|
||||
- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні сесій/статусу Gateway, а під час налагодження навантажень постачальника запускайте
|
||||
Gateway із `--raw-stream --raw-stream-path <path>`.
|
||||
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед model
|
||||
resolution для agent turns; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить assistant output.
|
||||
- Для підтвердження effective session model використовуйте `openclaw sessions` або
|
||||
поверхні session/status Gateway, а під час налагодження provider payloads запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
### Повільне налаштування інструментів плагіна
|
||||
### Повільне налаштування інструментів Plugin
|
||||
|
||||
Якщо ходи агента, здається, зависають під час підготовки інструментів, увімкніть трасувальне логування та
|
||||
перевірте рядки часу виконання фабрик інструментів плагінів:
|
||||
Якщо agent turns ніби зависають під час підготовки tools, увімкніть trace logging і
|
||||
перевірте рядки часу виконання plugin tool factory:
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -370,22 +367,28 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
Зведення перелічує загальний час фабрик і найповільніші фабрики інструментів плагінів,
|
||||
зокрема ідентифікатор плагіна, оголошені назви інструментів, форму результату й те, чи є інструмент
|
||||
необов’язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика займає
|
||||
щонайменше 1 с або загальна підготовка фабрик інструментів плагінів займає щонайменше 5 с.
|
||||
Зведення перелічує total factory time і найповільніші plugin tool factories,
|
||||
зокрема id Plugin, оголошені tool names, result shape і чи є tool
|
||||
optional. Повільні рядки підвищуються до warnings, коли один factory займає
|
||||
щонайменше 1s або загальна підготовка plugin tool factory займає щонайменше 5s.
|
||||
|
||||
Якщо один плагін домінує за часом, перевірте його runtime-реєстрації:
|
||||
OpenClaw кешує успішні результати plugin tool factory для повторних resolutions
|
||||
із тим самим effective request context. Cache key включає effective
|
||||
runtime config, workspace, agent/session ids, sandbox policy, browser settings,
|
||||
delivery context, requester identity і ownership state, тому factories, які
|
||||
залежать від цих trusted fields, повторно виконуються, коли context змінюється.
|
||||
|
||||
Якщо один Plugin домінує за часом, перевірте його runtime registrations:
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
Потім оновіть, перевстановіть або вимкніть цей плагін. Автори плагінів мають переносити
|
||||
дороге завантаження залежностей за шлях виконання інструмента, а не виконувати його
|
||||
всередині фабрики інструмента.
|
||||
Потім оновіть, перевстановіть або вимкніть цей Plugin. Автори Plugin мають переносити
|
||||
дороге завантаження залежностей за шлях виконання tool, замість того щоб робити це
|
||||
всередині tool factory.
|
||||
|
||||
### Дублювання власності каналу або інструмента
|
||||
### Дублювання ownership каналу або tool
|
||||
|
||||
Симптоми:
|
||||
|
||||
@ -393,35 +396,35 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
Це означає, що кілька ввімкнених плагінів намагаються володіти тим самим каналом,
|
||||
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній плагін каналу,
|
||||
встановлений поруч із вбудованим плагіном, який тепер надає той самий ідентифікатор каналу.
|
||||
Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим channel,
|
||||
setup flow або tool name. Найпоширеніша причина — зовнішній channel Plugin,
|
||||
встановлений поруч із bundled plugin, який тепер надає той самий channel id.
|
||||
|
||||
Кроки налагодження:
|
||||
|
||||
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений плагін
|
||||
і його походження.
|
||||
- Запустіть `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного плагіна й
|
||||
порівняйте `channels`, `channelConfigs`, `tools` і діагностику.
|
||||
- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
пакетів плагінів, щоб збережені метадані відображали поточне встановлення.
|
||||
- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації.
|
||||
- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin
|
||||
і origin.
|
||||
- Виконайте `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного Plugin і
|
||||
порівняйте `channels`, `channelConfigs`, `tools` і diagnostics.
|
||||
- Виконайте `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
plugin packages, щоб збережені metadata відображали поточний install.
|
||||
- Перезапустіть Gateway після змін install, registry або config.
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
- Якщо один плагін навмисно замінює інший для того самого ідентифікатора каналу, бажаний
|
||||
плагін має оголосити `channelConfigs.<channel-id>.preferOver` з
|
||||
ідентифікатором плагіна з нижчим пріоритетом. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Якщо дублювання випадкове, вимкніть один бік за допомогою
|
||||
`plugins.entries.<plugin-id>.enabled: false` або видаліть застаріле встановлення
|
||||
плагіна.
|
||||
- Якщо ви явно ввімкнули обидва плагіни, OpenClaw зберігає цей запит і
|
||||
повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти,
|
||||
що належать плагіну, щоб runtime-поверхня була однозначною.
|
||||
- Якщо один Plugin навмисно замінює інший для того самого channel id, бажаний
|
||||
Plugin має оголосити `channelConfigs.<channel-id>.preferOver` з
|
||||
id Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Якщо дублювання випадкове, вимкніть один бік через
|
||||
`plugins.entries.<plugin-id>.enabled: false` або видаліть застарілий install
|
||||
Plugin.
|
||||
- Якщо ви явно ввімкнули обидва Plugins, OpenClaw зберігає цей запит і
|
||||
повідомляє про conflict. Виберіть одного owner для channel або перейменуйте належні Plugin
|
||||
tools, щоб runtime surface була однозначною.
|
||||
|
||||
## Слоти плагінів (ексклюзивні категорії)
|
||||
## Slots Plugin (exclusive categories)
|
||||
|
||||
Деякі категорії є ексклюзивними (одночасно активна лише одна):
|
||||
Деякі categories є exclusive (одночасно активна лише одна):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -434,10 +437,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що він контролює | Типове значення |
|
||||
| Slot | Що контролює | Default |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | Плагін Active Memory | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
| `memory` | Active memory Plugin | `memory-core` |
|
||||
| `contextEngine` | Active context engine | `legacy` (built-in) |
|
||||
|
||||
## Довідник CLI
|
||||
|
||||
@ -487,55 +490,80 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Вбудовані плагіни постачаються з OpenClaw. Багато з них увімкнені типово (наприклад
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований браузерний
|
||||
плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable <id>`.
|
||||
Bundled plugins постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
|
||||
bundled model providers, bundled speech providers і bundled browser
|
||||
Plugin). Інші bundled plugins усе ще потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
плагінів. Це не підтримується з `--link`, який повторно використовує вихідний шлях замість
|
||||
копіювання поверх керованої цілі встановлення.
|
||||
`--force` перезаписує наявний installed Plugin або hook pack на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для routine upgrades tracked npm
|
||||
Plugins. Він не підтримується з `--link`, який повторно використовує source path замість
|
||||
копіювання поверх managed install target.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
ідентифікатор встановленого плагіна до цього allowlist перед його ввімкненням. Якщо той самий ідентифікатор плагіна
|
||||
наявний у `plugins.deny`, встановлення видаляє цей застарілий deny-запис, щоб
|
||||
явне встановлення можна було одразу завантажити після перезапуску.
|
||||
id installed Plugin до цього allowlist перед його ввімкненням. Якщо той самий id Plugin
|
||||
присутній у `plugins.deny`, install видаляє цей застарілий deny entry, щоб
|
||||
explicit install можна було завантажити одразу після restart.
|
||||
|
||||
OpenClaw зберігає сталий локальний реєстр плагінів як модель холодного читання для
|
||||
інвентарю плагінів, власності внесків і планування запуску. Потоки встановлення, оновлення,
|
||||
видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану плагіна.
|
||||
Той самий файл `plugins/installs.json` зберігає сталі метадані встановлення в
|
||||
верхньорівневому `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо
|
||||
OpenClaw зберігає постійний локальний реєстр Plugin як холодну модель читання для
|
||||
інвентаризації Plugin, володіння внесками та планування запуску. Потоки встановлення, оновлення,
|
||||
видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану Plugin.
|
||||
Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення в
|
||||
верхньорівневому `installRecords` і відновлювані метадані маніфесту в `plugins`. Якщо
|
||||
реєстр відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його подання маніфестів із записів встановлення, політики конфігурації та
|
||||
метаданих маніфестів/пакетів без завантаження runtime-модулів плагінів.
|
||||
метаданих маніфесту/пакета без завантаження runtime-модулів Plugin.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
npm package spec з dist-tag або точною версією розв’язує назву пакета
|
||||
назад до відстежуваного запису плагіна й записує новий spec для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переміщує точно закріплене встановлення назад на
|
||||
типову release line реєстру. Якщо встановлений npm-плагін уже відповідає
|
||||
розв’язаній версії та записаній ідентичності артефакта, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування конфігурації.
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із відстежуваним записом Plugin і записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переводить точно закріплене встановлення назад на
|
||||
стандартну лінію випусків реєстру. Якщо встановлений npm Plugin уже відповідає
|
||||
розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або перезапису конфігурації.
|
||||
|
||||
`--pin` працює лише з npm. Він не підтримується з `--marketplace`, тому що встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
|
||||
`--pin` працює лише з npm. Він не підтримується з `--marketplace`, тому що
|
||||
встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації.
|
||||
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних спрацювань вбудованого сканера небезпечного коду. Воно дає змогу продовжити встановлення й оновлення плагінів попри вбудовані знахідки рівня `critical`, але все одно не обходить блокування політик `before_install` плагіна або блокування через збій сканування. Сканування під час встановлення ігнорує типові тестові файли й каталоги, як-от `tests/`, `__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки; оголошені runtime-точки входу плагіна все одно скануються, навіть якщо використовують одну з цих назв.
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення
|
||||
Plugin і оновлення Plugin продовжуватися попри вбудовані знахідки `critical`, але все одно
|
||||
не обходить блокування політики `before_install` Plugin або блокування через помилку сканування.
|
||||
Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`,
|
||||
`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки;
|
||||
оголошені runtime-точки входу Plugin все одно скануються, навіть якщо вони використовують одну з
|
||||
цих назв.
|
||||
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills, підтримані Gateway, натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub.
|
||||
Цей CLI-прапорець застосовується лише до потоків встановлення/оновлення Plugin. Встановлення
|
||||
залежностей Skills, підтримані Gateway, натомість використовують відповідне перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим
|
||||
потоком завантаження/встановлення Skills із ClawHub.
|
||||
|
||||
Якщо плагін, який ви опублікували в ClawHub, приховано або заблоковано скануванням, відкрийте панель ClawHub або виконайте `clawhub package rescan <name>`, щоб попросити ClawHub перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному комп’ютері; він не просить ClawHub повторно просканувати плагін і не робить заблокований реліз публічним.
|
||||
Якщо Plugin, який ви опублікували в ClawHub, приховано або заблоковано скануванням, відкрийте
|
||||
панель ClawHub або запустіть `clawhub package rescan <name>`, щоб попросити ClawHub перевірити
|
||||
його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій власній
|
||||
машині; він не просить ClawHub повторно сканувати Plugin і не робить заблокований випуск
|
||||
публічним.
|
||||
|
||||
Сумісні пакети беруть участь у тому самому потоці списку/перевірки/увімкнення/вимкнення плагінів. Поточна підтримка runtime включає Skills пакета, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex.
|
||||
Сумісні bundles беруть участь у тому самому потоці переліку/перегляду/увімкнення/вимкнення
|
||||
Plugin. Поточна runtime-підтримка охоплює Skills у bundles, Claude command-skills,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті
|
||||
`lspServers`, Cursor command-skills, а також сумісні каталоги хуків Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості пакета, а також підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості bundle, а також
|
||||
підтримувані або непідтримувані записи серверів MCP і LSP для Plugin, підтриманих bundle.
|
||||
|
||||
Джерелами marketplace можуть бути відома назва marketplace Claude з `~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. Для віддалених marketplace записи плагінів мають залишатися всередині клонованого репозиторію marketplace і використовувати лише джерела з відносними шляхами.
|
||||
Джерела marketplace можуть бути відомою назвою Claude marketplace з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або шляхом
|
||||
`marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або git URL. Для віддалених marketplace записи Plugin мають залишатися всередині
|
||||
клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів.
|
||||
|
||||
Див. [довідник CLI `openclaw plugins`](/uk/cli/plugins) для повних відомостей.
|
||||
Докладні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
|
||||
## Огляд API Plugin
|
||||
## Огляд Plugin API
|
||||
|
||||
Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші плагіни ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають використовувати `register`.
|
||||
Нативні Plugin експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
Plugin можуть усе ще використовувати `activate(api)` як застарілий псевдонім, але нові Plugin мають
|
||||
використовувати `register`.
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -555,60 +583,75 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації плагіна. Завантажувач усе ще відступає до `activate(api)` для старіших плагінів, але вбудовані плагіни й нові зовнішні плагіни мають вважати `register` публічним контрактом.
|
||||
OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації
|
||||
Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugin,
|
||||
але вбудовані Plugin і нові зовнішні Plugin мають розглядати `register` як
|
||||
публічний контракт.
|
||||
|
||||
`api.registrationMode` повідомляє плагіну, чому його вхід завантажується:
|
||||
`api.registrationMode` повідомляє Plugin, чому його точку входу завантажують:
|
||||
|
||||
| Режим | Значення |
|
||||
| Режим | Значення |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Активація runtime. Реєструйте інструменти, хуки, сервіси, команди, маршрути й інші живі побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструйте провайдерів і метадані; довірений код входу плагіна може завантажуватися, але пропускайте живі побічні ефекти. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через легковаговий вхід налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен runtime-вхід. |
|
||||
| `cli-metadata` | Лише збирання метаданих команд CLI. |
|
||||
| `full` | Runtime-активація. Реєструйте інструменти, хуки, служби, команди, маршрути та інші живі побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструйте провайдерів і метадані; довірений код входу Plugin може завантажуватися, але пропускайте живі побічні ефекти. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через легку точку входу налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібна runtime-точка входу. |
|
||||
| `cli-metadata` | Лише збирання метаданих CLI-команд. |
|
||||
|
||||
Входи плагінів, які відкривають сокети, бази даних, фонових працівників або довгоживучі клієнти, мають захищати ці побічні ефекти через `api.registrationMode === "full"`. Завантаження для виявлення кешуються окремо від завантажень активації й не замінюють запущений реєстр Gateway. Виявлення не активує, але не є вільним від імпорту: OpenClaw може виконати довірений вхід плагіна або модуль канального плагіна, щоб побудувати знімок. Тримайте верхні рівні модулів легковаговими й без побічних ефектів, а мережевих клієнтів, підпроцеси, слухачі, читання облікових даних і запуск сервісів переміщуйте за шляхи повного runtime.
|
||||
Точки входу Plugin, які відкривають сокети, бази даних, фонові воркери або довгоживучі
|
||||
клієнти, мають захищати ці побічні ефекти через `api.registrationMode === "full"`.
|
||||
Завантаження discovery кешуються окремо від активаційних завантажень і не замінюють
|
||||
запущений реєстр Gateway. Discovery не активує, але не є вільним від імпорту:
|
||||
OpenClaw може виконувати довірену точку входу Plugin або модуль Plugin каналу, щоб побудувати
|
||||
знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а мережеві
|
||||
клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб переносіть
|
||||
за шляхи повного runtime.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | -------------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потокове STT |
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потоковий STT |
|
||||
| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Провайдер отримання / скрапінгу з web |
|
||||
| `registerWebSearchProvider` | Пошук у web |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фоновий сервіс |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Провайдер web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP-ендпоінт |
|
||||
| `registerCommand` / `registerCli` | CLI-команди |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фонова служба |
|
||||
|
||||
Поведінка захисту хуків для типізованих хуків життєвого циклу:
|
||||
Поведінка запобіжників хуків для типізованих хуків життєвого циклу:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` не виконує дії й не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` не виконує дії й не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` не виконує дії й не скасовує попереднє скасування.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
|
||||
|
||||
Нативний app-server Codex повертає події нативних інструментів Codex через міст у цю поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex `PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. Точна межа підтримки runtime Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
|
||||
Нативний Codex app-server мостить події нативних інструментів Codex назад у цю
|
||||
поверхню хуків. Plugin можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex
|
||||
`PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex.
|
||||
Точна межа підтримки runtime Codex міститься в
|
||||
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
|
||||
- [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
|
||||
- [Створення Plugin](/uk/plugins/building-plugins) — створіть власний Plugin
|
||||
- [Bundles Plugin](/uk/plugins/bundles) — сумісність bundle Codex/Claude/Cursor
|
||||
- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагін
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin
|
||||
- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Плагіни спільноти](/uk/plugins/community) — списки сторонніх плагінів
|
||||
- [Plugin спільноти](/uk/plugins/community) — сторонні списки
|
||||
|
||||
Loading…
Reference in New Issue
Block a user