chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3486fc6b37
commit
5e1a39ad1e
@ -1,48 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Зміна поведінки оновлення OpenClaw, doctor, приймання пакетів або встановлення Plugin
|
||||
- Підготовка або схвалення реліз-кандидата
|
||||
- Налагодження оновлення пакета, очищення залежностей Plugin або регресій установлення Plugin
|
||||
- Зміна поведінки оновлення, doctor, приймання пакетів або встановлення Plugin в OpenClaw
|
||||
- Підготовка або затвердження реліз-кандидата
|
||||
- Налагодження оновлення пакета, очищення залежностей Plugin або регресій встановлення Plugin
|
||||
sidebarTitle: Update and plugin tests
|
||||
summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення та оновлення Plugin
|
||||
title: 'Тестування: оновлення та Plugin'
|
||||
summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення/оновлення Plugin
|
||||
title: 'Тестування: оновлення та плагіни'
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T23:38:43Z"
|
||||
generated_at: "2026-05-02T02:02:09Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4d4b52047b9b80273e2d93b97e647e5e9c93d93910828fdce010568f3ea81390
|
||||
source_hash: b1999106b52d2539a6ee0fd7cd88ebb3515c8726e080d4031d7bf421fb99de36
|
||||
source_path: help/testing-updates-plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Це спеціальний контрольний список для валідації оновлень і Plugin. Мета
|
||||
проста: довести, що інстальований пакет може оновити реальний стан користувача,
|
||||
відновити застарілий успадкований стан через `doctor` і все ще встановлювати,
|
||||
завантажувати, оновлювати та видаляти plugins із підтримуваних джерел.
|
||||
Це окремий контрольний список для перевірки оновлень і Plugin. Мета
|
||||
проста: довести, що інстальований пакет може оновлювати реальний стан користувача, виправляти застарілий
|
||||
legacy-стан через `doctor` і надалі встановлювати, завантажувати, оновлювати та видаляти
|
||||
Plugin з підтримуваних джерел.
|
||||
|
||||
Ширшу карту тестового раннера див. у [Тестування](/uk/help/testing). Про ключі
|
||||
live-провайдерів і набори тестів, що торкаються мережі, див.
|
||||
[Live-тестування](/uk/help/testing-live).
|
||||
Ширшу мапу засобів запуску тестів див. у [Тестування](/uk/help/testing). Для live-ключів провайдерів
|
||||
і наборів тестів, що торкаються мережі, див. [Live-тестування](/uk/help/testing-live).
|
||||
|
||||
## Що ми захищаємо
|
||||
|
||||
Тести оновлення та Plugin захищають такі контракти:
|
||||
Тести оновлень і Plugin захищають такі контракти:
|
||||
|
||||
- Tarball пакета повний, має чинний `dist/postinstall-inventory.json` і не
|
||||
залежить від розпакованих файлів репозиторію.
|
||||
- Користувач може перейти зі старішого опублікованого пакета на кандидатний
|
||||
пакет без втрати конфігурації, агентів, сесій, робочих просторів, allowlist
|
||||
Plugin або конфігурації каналу.
|
||||
- `openclaw doctor --fix --non-interactive` володіє шляхами очищення та
|
||||
відновлення успадкованого стану. Startup не має розростатися прихованими
|
||||
міграціями сумісності для застарілого стану Plugin.
|
||||
- Встановлення Plugin працює з локальних директорій, git-репозиторіїв,
|
||||
npm-пакетів і шляху реєстру ClawHub.
|
||||
- npm-залежності Plugin встановлюються в керований корінь npm, скануються перед
|
||||
довірою та видаляються через npm під час uninstall, щоб підняті залежності не
|
||||
- Tarball пакета повний, має чинний `dist/postinstall-inventory.json`
|
||||
і не залежить від нерозпакованих файлів репозиторію.
|
||||
- Користувач може перейти зі старішого опублікованого пакета на пакет-кандидат
|
||||
без втрати конфігурації, агентів, сесій, робочих просторів, allowlist Plugin або
|
||||
конфігурації каналів.
|
||||
- `openclaw doctor --fix --non-interactive` відповідає за очищення та виправлення
|
||||
legacy-шляхів. Запуск не повинен обростати прихованими міграціями сумісності для застарілого
|
||||
стану Plugin.
|
||||
- Встановлення Plugin працює з локальних каталогів, git-репозиторіїв, npm-пакетів і
|
||||
шляху реєстру ClawHub.
|
||||
- npm-залежності Plugin встановлюються в керований npm root, скануються перед
|
||||
довірою й видаляються через npm під час деінсталяції, щоб hoisted-залежності не
|
||||
залишалися.
|
||||
- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення,
|
||||
розв’язане джерело та ввімкнений стан залишаються неушкодженими.
|
||||
- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, resolved
|
||||
source, структура встановлених залежностей і ввімкнений стан залишаються незмінними.
|
||||
|
||||
## Локальне підтвердження під час розробки
|
||||
|
||||
@ -54,33 +53,31 @@ pnpm check:changed
|
||||
pnpm test:changed
|
||||
```
|
||||
|
||||
Для змін у встановленні, видаленні, залежностях Plugin або package-inventory
|
||||
також запускайте сфокусовані тести, що покривають відредагований seam:
|
||||
Для змін у встановленні, видаленні, залежностях Plugin або package-inventory також
|
||||
запустіть цільові тести, що покривають відредаговану межу:
|
||||
|
||||
```bash
|
||||
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
|
||||
```
|
||||
|
||||
Перш ніж будь-яка package Docker lane споживатиме tarball, доведіть артефакт
|
||||
пакета:
|
||||
Перш ніж будь-яка package Docker lane використає tarball, перевірте артефакт пакета:
|
||||
|
||||
```bash
|
||||
pnpm release:check
|
||||
```
|
||||
|
||||
`release:check` запускає перевірки drift для config/docs/API, записує package
|
||||
dist inventory, запускає `npm pack --dry-run`, відхиляє заборонені запаковані
|
||||
файли, встановлює tarball у тимчасовий prefix, запускає postinstall і перевіряє
|
||||
smoke для bundled channel entrypoints.
|
||||
`release:check` запускає перевірки дрейфу config/docs/API, записує package dist
|
||||
inventory, запускає `npm pack --dry-run`, відхиляє заборонені запаковані файли, встановлює
|
||||
tarball у тимчасовий prefix, запускає postinstall і виконує smoke-перевірку bundled channel
|
||||
entrypoints.
|
||||
|
||||
## Docker lanes
|
||||
|
||||
Docker lanes є підтвердженням продуктового рівня. Вони встановлюють або
|
||||
оновлюють реальний пакет усередині Linux-контейнерів і перевіряють поведінку
|
||||
через CLI-команди, startup Gateway, HTTP-проби, RPC-статус і стан файлової
|
||||
системи.
|
||||
Docker lanes є product-level підтвердженням. Вони встановлюють або оновлюють реальний
|
||||
пакет у Linux-контейнерах і перевіряють поведінку через CLI-команди,
|
||||
запуск Gateway, HTTP-проби, RPC-статус і стан файлової системи.
|
||||
|
||||
Під час ітерацій використовуйте сфокусовані lanes:
|
||||
Під час ітерацій використовуйте цільові lanes:
|
||||
|
||||
```bash
|
||||
pnpm test:docker:plugins
|
||||
@ -92,30 +89,28 @@ pnpm test:docker:update-migration
|
||||
|
||||
Важливі lanes:
|
||||
|
||||
- `test:docker:plugins` валідує smoke встановлення Plugin, встановлення з
|
||||
локальних папок, локальні папки з попередньо встановленими залежностями,
|
||||
git-встановлення із залежностями пакета, встановлення залежностей npm-пакета,
|
||||
встановлення з локальної ClawHub fixture, поведінку marketplace update, а
|
||||
також enable/inspect для Claude-bundle. Установіть
|
||||
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався
|
||||
герметичним/offline.
|
||||
- `test:docker:plugins` перевіряє smoke встановлення Plugin, встановлення з локальної папки,
|
||||
skip-поведінку оновлення локальної папки, локальні папки з попередньо встановленими
|
||||
залежностями, встановлення `file:` пакетів, git-встановлення з виконанням CLI, оновлення
|
||||
moving-ref у git, встановлення з npm registry з hoisted transitive
|
||||
dependencies, no-op оновлення npm, встановлення з локальної ClawHub fixture і no-op
|
||||
оновлення, поведінку оновлення marketplace та ввімкнення/інспекцію Claude-bundle. Установіть
|
||||
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався герметичним/offline.
|
||||
- `test:docker:plugin-update` перевіряє, що незмінений встановлений Plugin не
|
||||
перевстановлюється й не втрачає метадані встановлення під час
|
||||
`openclaw plugins update`.
|
||||
- `test:docker:upgrade-survivor` встановлює кандидатний tarball поверх брудної
|
||||
old-user fixture, запускає оновлення пакета плюс non-interactive doctor,
|
||||
потім запускає loopback Gateway і перевіряє збереження стану.
|
||||
- `test:docker:published-upgrade-survivor` спочатку встановлює опублікований
|
||||
baseline, конфігурує його через baked рецепт `openclaw config set`, оновлює
|
||||
його до кандидатного tarball, запускає doctor, перевіряє очищення
|
||||
успадкованого стану, запускає Gateway і пробує `/healthz`, `/readyz` та
|
||||
RPC-статус.
|
||||
- `test:docker:update-migration` є cleanup-heavy lane для published-update. Вона
|
||||
стартує з налаштованого користувацького стану в стилі Discord/Telegram,
|
||||
запускає baseline doctor, щоб налаштовані залежності Plugin мали шанс
|
||||
матеріалізуватися, засіває уламки успадкованих залежностей Plugin для
|
||||
налаштованого packaged Plugin, оновлює до кандидатного tarball і вимагає, щоб
|
||||
post-update doctor видалив legacy dependency roots.
|
||||
перевстановлюється й не втрачає install metadata під час `openclaw plugins update`.
|
||||
- `test:docker:upgrade-survivor` встановлює tarball-кандидат поверх dirty
|
||||
old-user fixture, запускає оновлення пакета плюс non-interactive doctor, потім запускає
|
||||
loopback Gateway і перевіряє збереження стану.
|
||||
- `test:docker:published-upgrade-survivor` спершу встановлює опублікований baseline,
|
||||
конфігурує його через вбудований рецепт `openclaw config set`, оновлює його до
|
||||
tarball-кандидата, запускає doctor, перевіряє legacy cleanup, запускає Gateway і
|
||||
пробує `/healthz`, `/readyz` та RPC-статус.
|
||||
- `test:docker:update-migration` є cleanup-heavy published-update lane. Він
|
||||
стартує з налаштованого Discord/Telegram-style стану користувача, запускає baseline
|
||||
doctor, щоб налаштовані залежності Plugin мали шанс матеріалізуватися, сіє
|
||||
legacy plugin dependency debris для налаштованого packaged plugin, оновлює до
|
||||
tarball-кандидата й вимагає, щоб post-update doctor видалив legacy
|
||||
dependency roots.
|
||||
|
||||
Корисні варіанти published-upgrade survivor:
|
||||
|
||||
@ -131,13 +126,13 @@ pnpm test:docker:published-upgrade-survivor
|
||||
|
||||
Доступні сценарії: `base`, `feishu-channel`, `bootstrap-persona`,
|
||||
`plugin-deps-cleanup`, `tilde-log-path` і `versioned-runtime-deps`. В aggregate runs
|
||||
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі
|
||||
сценарії, сформовані за reported issues.
|
||||
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі reported
|
||||
issue-shaped scenarios.
|
||||
|
||||
Повна update migration навмисно відокремлена від Full Release CI. Використовуйте
|
||||
ручний workflow `Update Migration`, коли release-питання звучить так: "чи може
|
||||
кожен опублікований stable release від 2026.4.23 і далі оновитися до цього
|
||||
кандидата та очистити уламки залежностей Plugin?":
|
||||
Повна міграція оновлень навмисно відокремлена від Full Release CI. Використовуйте
|
||||
ручний workflow `Update Migration`, коли release-питання звучить так: "чи може кожен
|
||||
опублікований stable release від 2026.4.23 і далі оновитися до цього кандидата та
|
||||
очистити plugin dependency debris?":
|
||||
|
||||
```bash
|
||||
gh workflow run update-migration.yml \
|
||||
@ -150,23 +145,22 @@ gh workflow run update-migration.yml \
|
||||
|
||||
## Package Acceptance
|
||||
|
||||
Package Acceptance є GitHub-native package gate. Він розв’язує один кандидатний
|
||||
пакет у tarball `package-under-test`, записує версію та SHA-256, потім запускає
|
||||
reusable Docker E2E lanes проти саме цього tarball. Workflow harness ref
|
||||
відокремлений від package source ref, тому поточна тестова логіка може
|
||||
валідувати старіші trusted releases.
|
||||
Package Acceptance — це GitHub-native package gate. Він визначає один candidate
|
||||
package у tarball `package-under-test`, записує version і SHA-256, а потім
|
||||
запускає reusable Docker E2E lanes проти саме цього tarball. Workflow harness
|
||||
ref відокремлений від package source ref, тому поточна логіка тестів може перевіряти
|
||||
старіші trusted releases.
|
||||
|
||||
Джерела кандидата:
|
||||
Джерела кандидатів:
|
||||
|
||||
- `source=npm`: валідувати `openclaw@beta`, `openclaw@latest` або точну
|
||||
- `source=npm`: перевірити `openclaw@beta`, `openclaw@latest` або точну
|
||||
опубліковану версію.
|
||||
- `source=ref`: запакувати trusted branch, tag або commit із вибраним поточним
|
||||
- `source=ref`: запакувати trusted branch, tag або commit з вибраним поточним
|
||||
harness.
|
||||
- `source=url`: валідувати HTTPS tarball з обов’язковим `package_sha256`.
|
||||
- `source=artifact`: повторно використати tarball, завантажений іншим Actions
|
||||
run.
|
||||
- `source=url`: перевірити HTTPS tarball з обов’язковим `package_sha256`.
|
||||
- `source=artifact`: повторно використати tarball, завантажений іншим Actions run.
|
||||
|
||||
Release checks викликають Package Acceptance з package/update/plugin set:
|
||||
Release checks викликають Package Acceptance із набором package/update/plugin:
|
||||
|
||||
```text
|
||||
doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update
|
||||
@ -180,16 +174,16 @@ published_upgrade_survivor_scenarios=reported-issues
|
||||
telegram_mode=mock-openai
|
||||
```
|
||||
|
||||
Це тримає package migration, перемикання каналу оновлень, очищення застарілих
|
||||
залежностей Plugin, offline-покриття Plugin, поведінку оновлення Plugin і
|
||||
Telegram package QA на одному розв’язаному артефакті.
|
||||
Це тримає міграцію пакета, перемикання update channel, очищення застарілих plugin dependency,
|
||||
offline-покриття Plugin, поведінку оновлення Plugin і Telegram package
|
||||
QA на одному resolved artifact.
|
||||
|
||||
`release-history` є обмеженим release-check sample: останні шість stable
|
||||
releases, `2026.4.23` і один старіший pre-date anchor. Для вичерпного покриття
|
||||
published update migration використовуйте `all-since-2026.4.23` в окремому
|
||||
workflow Update Migration замість Full Release CI.
|
||||
`release-history` — це bounded release-check sample: останні шість stable releases,
|
||||
`2026.4.23` і один старіший pre-date anchor. Для вичерпного покриття published update
|
||||
migration використовуйте `all-since-2026.4.23` в окремому workflow Update Migration
|
||||
замість Full Release CI.
|
||||
|
||||
Запустіть package profile вручну під час валідації кандидата перед release:
|
||||
Запустіть package profile вручну під час перевірки кандидата перед релізом:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -203,69 +197,71 @@ gh workflow run package-acceptance.yml \
|
||||
-f telegram_mode=mock-openai
|
||||
```
|
||||
|
||||
Використовуйте `suite_profile=product`, коли release-питання включає MCP
|
||||
channels, cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте
|
||||
`suite_profile=full` лише тоді, коли потрібне повне покриття Docker release-path.
|
||||
Використовуйте `suite_profile=product`, коли release-питання охоплює MCP channels,
|
||||
cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте `suite_profile=full`
|
||||
лише тоді, коли потрібне повне покриття Docker release-path.
|
||||
|
||||
## Типовий release
|
||||
## Типовий варіант для релізу
|
||||
|
||||
Для release candidates типовий стек підтвердження такий:
|
||||
Для release candidates типовий proof stack такий:
|
||||
|
||||
1. `pnpm check:changed` і `pnpm test:changed` для source-level регресій.
|
||||
2. `pnpm release:check` для цілісності артефакту пакета.
|
||||
3. Package Acceptance profile `package` або release-check custom package
|
||||
lanes для контрактів install/update/plugin.
|
||||
3. Package Acceptance `package` profile або release-check custom package
|
||||
lanes для install/update/plugin contracts.
|
||||
4. Cross-OS release checks для OS-specific installer, onboarding і platform
|
||||
behavior.
|
||||
5. Live-набори лише тоді, коли змінена поверхня торкається поведінки провайдера
|
||||
або hosted-service.
|
||||
5. Live-набори лише тоді, коли змінена surface зачіпає provider або hosted-service
|
||||
behavior.
|
||||
|
||||
На машинах мейнтейнерів broad gates і Docker/package product proof мають
|
||||
запускатися в Testbox, якщо явно не виконується локальне підтвердження.
|
||||
На maintainer machines broad gates і Docker/package product proof мають запускатися
|
||||
в Testbox, якщо явно не виконується local proof.
|
||||
|
||||
## Успадкована сумісність
|
||||
## Legacy-сумісність
|
||||
|
||||
Поблажливість сумісності вузька й обмежена в часі:
|
||||
Compatibility leniency вузька й обмежена в часі:
|
||||
|
||||
- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть терпіти
|
||||
вже shipped gaps у package metadata в Package Acceptance.
|
||||
- Опублікований пакет `2026.4.26` може попереджати про local build metadata
|
||||
stamp files, які вже shipped.
|
||||
- Пізніші пакети мають задовольняти сучасні контракти. Ті самі gaps мають
|
||||
падати замість warning або skipping.
|
||||
- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть толерувати
|
||||
вже випущені прогалини package metadata у Package Acceptance.
|
||||
- Опублікований пакет `2026.4.26` може попереджати про local build metadata stamp
|
||||
files, які вже були випущені.
|
||||
- Пізніші пакети мають задовольняти сучасні контракти. Ті самі прогалини призводять до failure замість
|
||||
warning або skipping.
|
||||
|
||||
Не додавайте нові startup migrations для цих старих форм. Додайте або розширте
|
||||
doctor repair, потім доведіть це за допомогою `upgrade-survivor` або
|
||||
`published-upgrade-survivor`.
|
||||
Не додавайте нові startup migrations для цих старих форм. Додайте або розширте doctor
|
||||
repair, а потім доведіть це через `upgrade-survivor` або `published-upgrade-survivor`.
|
||||
|
||||
## Додавання покриття
|
||||
|
||||
Коли змінюєте поведінку update або Plugin, додавайте покриття на найнижчому
|
||||
рівні, який може впасти з правильної причини:
|
||||
Коли змінюєте поведінку оновлення або Plugin, додавайте покриття на найнижчому рівні, який
|
||||
може впасти з правильної причини:
|
||||
|
||||
- Чиста path або metadata logic: unit test поруч із джерелом.
|
||||
- Поведінка package inventory або packed-file: `package-dist-inventory` або
|
||||
tarball checker test.
|
||||
- CLI install/update behavior: Docker lane assertion або fixture.
|
||||
- Чиста логіка шляхів або metadata: unit test поруч із source.
|
||||
- Поведінка package inventory або packed-file: `package-dist-inventory` або tarball
|
||||
checker test.
|
||||
- Поведінка CLI install/update: Docker lane assertion або fixture.
|
||||
- Поведінка published-release migration: сценарій `published-upgrade-survivor`.
|
||||
- Поведінка registry/package source: fixture `test:docker:plugins` або сервер
|
||||
ClawHub fixture.
|
||||
- Поведінка registry/package source: fixture `test:docker:plugins` або ClawHub
|
||||
fixture server.
|
||||
- Поведінка dependency layout або cleanup: перевіряйте і runtime execution, і
|
||||
filesystem boundary. npm-залежності можуть бути hoisted під managed npm
|
||||
root, тому тести мають доводити, що root сканується/очищується, замість припущення про
|
||||
package-local дерево `node_modules`.
|
||||
|
||||
Нові Docker fixtures за замовчуванням мають бути герметичними. Використовуйте
|
||||
локальні fixture registries і fake packages, якщо метою тесту не є live registry
|
||||
behavior.
|
||||
Нові Docker fixtures за замовчуванням мають бути герметичними. Використовуйте локальні fixture registries і
|
||||
fake packages, якщо метою тесту не є live registry behavior.
|
||||
|
||||
## Тріаж збоїв
|
||||
|
||||
Починайте з ідентичності артефакту:
|
||||
|
||||
- Summary Package Acceptance `resolve_package`: source, version, SHA-256 і
|
||||
- Summary `resolve_package` у Package Acceptance: source, version, SHA-256 і
|
||||
artifact name.
|
||||
- Docker artifacts: `.artifacts/docker-tests/**/summary.json`,
|
||||
`failures.json`, lane logs і rerun commands.
|
||||
- Summary upgrade survivor: `.artifacts/upgrade-survivor/summary.json`,
|
||||
включно з baseline version, candidate version, scenario, phase timings і
|
||||
- Upgrade survivor summary: `.artifacts/upgrade-survivor/summary.json`,
|
||||
зокрема baseline version, candidate version, scenario, phase timings і
|
||||
recipe steps.
|
||||
|
||||
Віддавайте перевагу повторному запуску саме failed exact lane з тим самим
|
||||
package artifact, а не повторному запуску всієї release umbrella.
|
||||
Надавайте перевагу повторному запуску exact lane, що впав, з тим самим package artifact замість
|
||||
повторного запуску всього release umbrella.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,75 +1,81 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви налагоджуєте встановлення пакетів Plugin
|
||||
- Ви налагоджуєте встановлення пакетів плагінів
|
||||
- Ви змінюєте поведінку запуску Plugin, doctor або встановлення через менеджер пакетів
|
||||
- Ви підтримуєте пакетовані інсталяції OpenClaw або маніфести вбудованих Plugin
|
||||
- Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести Plugin, що постачаються в комплекті
|
||||
sidebarTitle: Dependencies
|
||||
summary: Як OpenClaw встановлює пакети Plugin і розв’язує залежності Plugin
|
||||
summary: Як OpenClaw встановлює Plugin-пакети та розв’язує залежності Plugin
|
||||
title: Розв’язання залежностей Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T01:52:11Z"
|
||||
generated_at: "2026-05-02T02:02:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 296263808a080909e6dbf0000a764d7539a7065f86772f7fcf5a86c1f11e1906
|
||||
source_hash: 43d8008c837d519fd7c886f9615ad53941da340d753b559dfb0a32877716bc1f
|
||||
source_path: plugins/dependency-resolution.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Розв’язання залежностей Plugin
|
||||
|
||||
OpenClaw виконує роботу із залежностями Plugin під час встановлення/оновлення. Завантаження під час виконання
|
||||
не запускає менеджери пакетів, не відновлює дерева залежностей і не змінює каталог
|
||||
OpenClaw виконує роботу із залежностями Plugin під час установлення/оновлення. Завантаження під час виконання
|
||||
не запускає менеджери пакетів, не ремонтує дерева залежностей і не змінює каталог
|
||||
пакета OpenClaw.
|
||||
|
||||
## Розподіл відповідальності
|
||||
|
||||
Пакети Plugin відповідають за власний граф залежностей:
|
||||
|
||||
- залежності часу виконання містяться в `dependencies` або
|
||||
- залежності часу виконання розміщуються в `dependencies` або
|
||||
`optionalDependencies` пакета Plugin
|
||||
- імпорти SDK/core є peer-залежностями або наданими імпортами OpenClaw
|
||||
- локальні Plugin для розробки приносять власні вже встановлені залежності
|
||||
- npm- і git-Plugin встановлюються в корені пакетів, керовані OpenClaw
|
||||
- імпорти SDK/ядра є peer-імпортами або наданими імпортами OpenClaw
|
||||
- локальні Plugin для розробки постачаються зі своїми вже встановленими залежностями
|
||||
- npm і git Plugin установлюються в корені пакетів, що належать OpenClaw
|
||||
|
||||
OpenClaw відповідає лише за життєвий цикл Plugin:
|
||||
|
||||
- виявити джерело Plugin
|
||||
- встановити або оновити пакет за явним запитом
|
||||
- установити або оновити пакет, коли це явно запитано
|
||||
- записати метадані встановлення
|
||||
- завантажити точку входу Plugin
|
||||
- завершитися з дієвою помилкою, коли бракує залежностей
|
||||
- завершити роботу з дієвою помилкою, коли залежності відсутні
|
||||
|
||||
## Корені встановлення
|
||||
|
||||
OpenClaw використовує стабільні корені для кожного джерела:
|
||||
|
||||
- npm-пакети встановлюються в `~/.openclaw/npm`
|
||||
- git-пакети клонуються в `~/.openclaw/git`
|
||||
- локальні/path/archive встановлення копіюються або посилаються без відновлення залежностей
|
||||
- пакети npm установлюються в `~/.openclaw/npm`
|
||||
- пакети git клонуються в `~/.openclaw/git`
|
||||
- локальні/шляхові/архівні встановлення копіюються або використовуються за посиланням без ремонту залежностей
|
||||
|
||||
npm-встановлення виконуються в npm-корені з:
|
||||
Встановлення npm виконуються в корені npm за допомогою:
|
||||
|
||||
```bash
|
||||
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
```
|
||||
|
||||
git-встановлення клонують або оновлюють репозиторій, а потім виконують:
|
||||
npm може підняти транзитивні залежності до `~/.openclaw/npm/node_modules` поруч із
|
||||
пакетом Plugin. OpenClaw сканує керований корінь npm перед тим, як довіряти
|
||||
встановленню, і використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті
|
||||
залежності часу виконання залишаються всередині керованої межі очищення.
|
||||
|
||||
Встановлення git клонують або оновлюють репозиторій, а потім виконують:
|
||||
|
||||
```bash
|
||||
npm install --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
```
|
||||
|
||||
Після цього встановлений Plugin завантажується з каталогу цього пакета, тому розв’язання
|
||||
`node_modules` у межах пакета працює так само, як для звичайного пакета Node.
|
||||
локальних для пакета та батьківських `node_modules` працює так само, як для звичайного
|
||||
пакета Node.
|
||||
|
||||
## Локальні Plugin
|
||||
|
||||
Локальні Plugin розглядаються як каталоги під контролем розробника. OpenClaw не
|
||||
запускає `npm install`, `pnpm install` або відновлення залежностей для них. Якщо локальний
|
||||
Plugin має залежності, встановіть їх у цьому Plugin перед його завантаженням.
|
||||
Локальні Plugin розглядаються як каталоги, керовані розробником. OpenClaw не
|
||||
виконує для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний
|
||||
Plugin має залежності, установіть їх у цьому Plugin перед його завантаженням.
|
||||
|
||||
Сторонні локальні Plugin на TypeScript можуть використовувати аварійний шлях Jiti. Запаковані
|
||||
JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативний
|
||||
Сторонні локальні Plugin TypeScript можуть використовувати аварійний шлях Jiti. Запаковані
|
||||
JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативні
|
||||
import/require замість Jiti.
|
||||
|
||||
## Запуск і перезавантаження
|
||||
@ -78,7 +84,7 @@ import/require замість Jiti.
|
||||
записи встановлення Plugin, обчислюють точку входу та завантажують її.
|
||||
|
||||
Якщо залежність відсутня під час виконання, Plugin не завантажується, а помилка
|
||||
має вказати оператору на явне виправлення:
|
||||
має вказати оператору явне виправлення:
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id>
|
||||
@ -87,37 +93,37 @@ openclaw doctor --fix
|
||||
```
|
||||
|
||||
`doctor --fix` може очистити застарілий стан залежностей, згенерований OpenClaw, і встановити
|
||||
налаштовані завантажувані Plugin, яких бракує в локальних записах встановлення.
|
||||
Він не відновлює залежності для вже встановленого локального Plugin.
|
||||
налаштовані завантажувані Plugin, яких немає в локальних записах встановлення.
|
||||
Він не ремонтує залежності для вже встановленого локального Plugin.
|
||||
|
||||
## Вбудовані Plugin
|
||||
|
||||
Легкі та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw.
|
||||
Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені до
|
||||
завантажуваного пакета на ClawHub/npm.
|
||||
Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені в
|
||||
завантажуваний пакет на ClawHub/npm.
|
||||
|
||||
Маніфести вбудованих Plugin не повинні запитувати staging залежностей. Велика або необов’язкова
|
||||
функціональність Plugin має пакуватися як звичайний Plugin і встановлюватися через
|
||||
Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велику або необов’язкову
|
||||
функціональність Plugin слід пакувати як звичайний Plugin і встановлювати через
|
||||
той самий шлях npm/git/ClawHub, що й сторонні Plugin.
|
||||
|
||||
У вихідних checkout OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після
|
||||
`pnpm install` вбудовані Plugin завантажуються з `extensions/<id>`, тож локальні для пакета
|
||||
workspace-залежності доступні, а зміни підхоплюються напряму. Розробка у вихідному
|
||||
checkout підтримується лише через pnpm; звичайний `npm install` у корені репозиторію
|
||||
залежності workspace доступні, а зміни підхоплюються напряму. Розробка з вихідного
|
||||
checkout підтримується лише з pnpm; звичайний `npm install` у корені репозиторію
|
||||
не є підтримуваним способом підготувати залежності вбудованих Plugin.
|
||||
|
||||
| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей |
|
||||
| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей |
|
||||
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
|
||||
| `npm install -g openclaw` | Зібране дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin |
|
||||
| Git checkout плюс `pnpm install` | Workspace-пакети `extensions/<id>` | pnpm-workspace, включно з власними залежностями кожного пакета Plugin |
|
||||
| `npm install -g openclaw` | Побудоване дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin |
|
||||
| Git checkout плюс `pnpm install` | Пакети workspace `extensions/<id>` | pnpm workspace, включно з власними залежностями кожного пакета Plugin |
|
||||
| `openclaw plugins install ...` | Керований корінь Plugin npm/git/ClawHub | Потік встановлення/оновлення Plugin |
|
||||
|
||||
## Очищення застарілого
|
||||
## Очищення застарілого стану
|
||||
|
||||
Старіші версії OpenClaw генерували корені залежностей вбудованих Plugin під час запуску або
|
||||
під час виправлення doctor. Поточне очищення doctor видаляє ці застарілі каталоги та
|
||||
симлінки, коли використано `--fix`, включно зі старими коренями `plugin-runtime-deps`,
|
||||
під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги та
|
||||
символьні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`,
|
||||
маніфестами `.openclaw-runtime-deps*`, згенерованими `node_modules` Plugin, каталогами
|
||||
етапу встановлення та локальними pnpm-сховищами пакетів.
|
||||
етапів встановлення та локальними для пакета сховищами pnpm.
|
||||
|
||||
Ці шляхи є лише застарілими залишками. Нові встановлення не повинні створювати їх.
|
||||
Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -4,24 +4,24 @@ read_when:
|
||||
- Розуміння правил виявлення та завантаження Plugin
|
||||
- Робота з пакетами Plugin, сумісними з Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Установлюйте, налаштовуйте та керуйте Plugin OpenClaw
|
||||
title: Plugins
|
||||
summary: Встановлюйте, налаштовуйте й керуйте плагінами OpenClaw
|
||||
title: Плагіни
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T01:11:02Z"
|
||||
generated_at: "2026-05-02T02:02:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: dee1689b502a1ce60f4921d216f8d8a00fbb131bc993cfabb4e0295825c1fdb2
|
||||
source_hash: 9e68612f5bf538ba8f38d96bd85a0b4f044e203ecf647caef070965a4a96d99b
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Plugins розширюють OpenClaw новими можливостями: channels, model providers,
|
||||
agent harnesses, tools, skills, speech, realtime transcription, realtime
|
||||
voice, media-understanding, image generation, video generation, web fetch, web
|
||||
search тощо. Деякі Plugins є **core** (постачаються з OpenClaw), інші
|
||||
є **external**. Більшість external Plugins публікуються та знаходяться через
|
||||
Плагіни розширюють OpenClaw новими можливостями: каналами, постачальниками моделей,
|
||||
оболонками агентів, інструментами, Skills, мовленням, транскрибуванням у реальному часі, голосом у реальному часі,
|
||||
розумінням медіа, генерацією зображень, генерацією відео, веб-отриманням, веб-пошуком
|
||||
тощо. Деякі плагіни є **основними** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх плагінів публікуються й знаходяться через
|
||||
[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих установлень і для
|
||||
тимчасового набору пакетів Plugins, що належать OpenClaw, доки ця міграція завершується.
|
||||
тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -32,7 +32,7 @@ search тощо. Деякі Plugins є **core** (постачаються з Ope
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Установіть Plugin">
|
||||
<Step title="Установіть плагін">
|
||||
```bash
|
||||
# From npm
|
||||
openclaw plugins install npm:@acme/openclaw-plugin
|
||||
@ -56,7 +56,7 @@ search тощо. Деякі Plugins є **core** (постачаються з Ope
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте Plugin">
|
||||
<Step title="Перевірте плагін">
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
|
||||
@ -64,14 +64,14 @@ search тощо. Деякі Plugins є **core** (постачаються з Ope
|
||||
openclaw <plugin-command> --help
|
||||
```
|
||||
|
||||
Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані tools, services, gateway
|
||||
methods, hooks або команди CLI, що належать Plugin. Звичайний `inspect` — це холодна
|
||||
перевірка manifest/registry, яка навмисно уникає імпорту runtime Plugin.
|
||||
Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, сервіси, методи Gateway,
|
||||
хуки або CLI-команди, що належать плагіну. Звичайний `inspect` є холодною
|
||||
перевіркою маніфесту/реєстру й навмисно уникає імпортування середовища виконання плагіна.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
Якщо ви віддаєте перевагу керуванню прямо з чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:<package>
|
||||
@ -79,73 +79,74 @@ search тощо. Деякі Plugins є **core** (постачаються з Ope
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
Шлях установлення використовує той самий resolver, що й CLI: локальний шлях/archive, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>`, явний `git:<repo>` або bare package
|
||||
spec (спочатку ClawHub, потім npm fallback).
|
||||
Шлях установлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>`, явний `git:<repo>` або просту специфікацію пакета
|
||||
(спочатку ClawHub, потім резервний npm).
|
||||
|
||||
Якщо конфігурація недійсна, установлення зазвичай безпечно завершується помилкою і спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-plugin
|
||||
для Plugins, які явно ввімкнули
|
||||
Якщо конфігурація недійсна, установлення зазвичай завершується закрито й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого плагіна
|
||||
для плагінів, які вмикають
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
Під час запуску Gateway недійсна конфігурація одного Plugin ізолюється до цього Plugin:
|
||||
запуск записує проблему `plugins.entries.<id>.config` у logs, пропускає цей Plugin під час
|
||||
завантаження та залишає інші Plugins і channels онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити погану конфігурацію Plugin у карантин, вимкнувши цей запис Plugin і видаливши
|
||||
його недійсне config payload; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли channel config посилається на Plugin, який більше не можна виявити, але той самий
|
||||
застарілий plugin id залишається в plugin config або install records, запуск Gateway
|
||||
записує warnings і пропускає цей channel замість блокування всіх інших channels.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі channel/plugin entries; невідомі
|
||||
channel keys без evidence застарілого Plugin усе одно не проходять validation, тож помилки введення
|
||||
залишаються видимими.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugins вважаються неактивними:
|
||||
запуск Gateway пропускає роботу з discovery/load Plugin, а `openclaw doctor` зберігає
|
||||
вимкнену plugin config замість автоматичного видалення. Повторно ввімкніть Plugins перед
|
||||
запуском doctor cleanup, якщо хочете видалити застарілі plugin ids.
|
||||
Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється до цього плагіна:
|
||||
запуск записує проблему `plugins.entries.<id>.config` у журнали, пропускає цей плагін під час
|
||||
завантаження та залишає інші плагіни й канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити неправильну конфігурацію плагіна в карантин, вимкнувши цей запис плагіна й видаливши
|
||||
його недійсний конфігураційний вміст; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на плагін, який більше не можна знайти, але той самий
|
||||
застарілий ідентифікатор плагіна залишається в конфігурації плагінів або записах установлення, запуск Gateway
|
||||
записує попередження й пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі
|
||||
ключі каналів без ознак застарілого плагіна все ще спричиняють помилку валідації, щоб друкарські помилки залишалися
|
||||
помітними.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються інертними:
|
||||
запуск Gateway пропускає виявлення/завантаження плагінів, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію плагінів замість автоматичного видалення. Знову ввімкніть плагіни перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори плагінів.
|
||||
|
||||
Установлення залежностей Plugin відбувається лише під час явних install/update або
|
||||
doctor repair flows. Запуск Gateway, перезавантаження конфігурації та runtime inspection
|
||||
не запускають package managers і не ремонтують dependency trees. Локальні Plugins уже повинні
|
||||
мати встановлені залежності, тоді як npm, git і ClawHub Plugins встановлюються
|
||||
під керованими OpenClaw plugin roots із package-local
|
||||
dependencies. External Plugins і custom load paths усе ще потрібно встановлювати
|
||||
через `openclaw plugins install`.
|
||||
Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) для життєвого циклу
|
||||
під час установлення.
|
||||
Установлення залежностей плагіна відбувається лише під час явних потоків установлення/оновлення або
|
||||
ремонту doctor. Запуск Gateway, перезавантаження конфігурації та інспекція середовища виконання
|
||||
не запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні плагіни вже повинні
|
||||
мати встановлені залежності, тоді як npm, git і ClawHub-плагіни
|
||||
встановлюються в керовані OpenClaw корені плагінів. Залежності npm можуть підійматися
|
||||
в межах керованого npm-кореня OpenClaw; установлення/оновлення сканує цей керований корінь перед
|
||||
довірою, а видалення прибирає керовані npm пакети через npm. Зовнішні плагіни
|
||||
й користувацькі шляхи завантаження все одно мають установлюватися через `openclaw plugins install`.
|
||||
Див. [Розв’язання залежностей плагінів](/uk/plugins/dependency-resolution) щодо
|
||||
життєвого циклу під час установлення.
|
||||
|
||||
Source checkouts — це pnpm workspaces. Якщо ви клонували OpenClaw, щоб працювати над bundled
|
||||
Plugins, запустіть `pnpm install`; після цього OpenClaw завантажує bundled Plugins з
|
||||
`extensions/<id>`, тож edits і package-local dependencies використовуються напряму.
|
||||
Звичайні npm root installs призначені для packaged OpenClaw, а не для розробки
|
||||
source checkout.
|
||||
Вихідні checkout-и є pnpm workspace-ами. Якщо ви клонуєте OpenClaw, щоб працювати над вбудованими
|
||||
плагінами, запустіть `pnpm install`; після цього OpenClaw завантажує вбудовані плагіни з
|
||||
`extensions/<id>`, тож редагування й локальні залежності пакета використовуються напряму.
|
||||
Звичайні кореневі встановлення npm призначені для запакованого OpenClaw, а не для розробки
|
||||
з вихідного checkout-а.
|
||||
|
||||
## Типи Plugin
|
||||
## Типи плагінів
|
||||
|
||||
OpenClaw розпізнає два формати Plugin:
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + runtime module; виконується in-process | Офіційні Plugins, пакети community npm |
|
||||
| **Bundle** | Codex/Claude/Cursor-compatible layout; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **Нативний** | `openclaw.plugin.json` + модуль середовища виконання; виконується в процесі | Офіційні плагіни, спільнотні npm-пакети |
|
||||
| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для деталей bundle.
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для деталей про bundle-и.
|
||||
|
||||
Якщо ви пишете native Plugin, почніть із [Створення Plugins](/uk/plugins/building-plugins)
|
||||
та [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете нативний плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins)
|
||||
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Точки входу пакета
|
||||
|
||||
Native plugin npm packages мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен entry має залишатися всередині package directory і розв’язуватися до читабельного
|
||||
runtime file або до TypeScript source file з inferred built JavaScript
|
||||
peer, наприклад від `src/index.ts` до `dist/index.js`.
|
||||
Npm-пакети нативних плагінів мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в читаний
|
||||
файл середовища виконання або у файл вихідного коду TypeScript з виведеним зібраним JavaScript-
|
||||
відповідником, наприклад `src/index.ts` до `dist/index.js`.
|
||||
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime files не розташовані за
|
||||
тими самими paths, що й source entries. Якщо він присутній, `runtimeExtensions` має містити
|
||||
рівно один entry для кожного `extensions` entry. Несумісні списки призводять до помилки install і
|
||||
plugin discovery замість мовчазного fallback до source paths. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його built
|
||||
JavaScript peer; цей файл обов’язковий, якщо його оголошено.
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані файли середовища виконання не розташовані
|
||||
за тими самими шляхами, що й вихідні записи. Якщо присутній `runtimeExtensions`, він має містити
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки спричиняють помилку встановлення й
|
||||
виявлення плагінів замість тихого повернення до вихідних шляхів. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його зібраного
|
||||
JavaScript-відповідника; цей файл є обов’язковим, коли оголошений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -157,21 +158,21 @@ JavaScript peer; цей файл обов’язковий, якщо його о
|
||||
}
|
||||
```
|
||||
|
||||
## Офіційні Plugins
|
||||
## Офіційні плагіни
|
||||
|
||||
### Пакети npm, що належать OpenClaw, під час міграції
|
||||
### Npm-пакети, що належать OpenClaw, під час міграції
|
||||
|
||||
ClawHub — основний шлях розповсюдження для більшості Plugins. Поточні packaged
|
||||
OpenClaw releases уже містять багато офіційних Plugins, тож у звичайних налаштуваннях
|
||||
їм не потрібні окремі npm installs. Доки кожен Plugin, що належить OpenClaw, не
|
||||
мігрує до ClawHub, OpenClaw усе ще постачає деякі `@openclaw/*` plugin packages на
|
||||
npm для older/custom installs і прямих npm workflows.
|
||||
ClawHub є основним шляхом розповсюдження для більшості плагінів. Поточні запаковані
|
||||
випуски OpenClaw уже містять багато офіційних плагінів, тому вони не потребують
|
||||
окремих npm-установлень у звичайних налаштуваннях. Доки кожен плагін, що належить OpenClaw, не
|
||||
мігрує до ClawHub, OpenClaw усе ще постачає деякі пакети плагінів `@openclaw/*` на
|
||||
npm для старіших/користувацьких установлень і прямих npm-процесів.
|
||||
|
||||
Якщо npm повідомляє про `@openclaw/*` plugin package як deprecated, ця package
|
||||
version походить зі старішого external package train. Використовуйте bundled Plugin з
|
||||
поточного OpenClaw або local checkout, доки не буде опубліковано новіший npm package.
|
||||
Якщо npm повідомляє про пакет плагіна `@openclaw/*` як застарілий, ця версія пакета
|
||||
належить до старішої зовнішньої гілки пакетів. Використовуйте вбудований плагін із
|
||||
поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
| Plugin | Пакет | Документація |
|
||||
| Плагін | Пакет | Документація |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/uk/channels/bluebubbles) |
|
||||
| Discord | `@openclaw/discord` | [Discord](/uk/channels/discord) |
|
||||
@ -187,7 +188,7 @@ version походить зі старішого external package train. Вик
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
|
||||
### Core (постачається з OpenClaw)
|
||||
### Основні (постачаються з OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнено за замовчуванням)">
|
||||
@ -198,12 +199,12 @@ version походить зі старішого external package train. Вик
|
||||
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory Plugins">
|
||||
- `memory-core` — bundled memory search (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — long-term memory на базі LanceDB з auto-recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук пам’яті (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb) для OpenAI-compatible
|
||||
налаштування embeddings, прикладів Ollama, recall limits і troubleshooting.
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb) для налаштування embeddings, сумісних з OpenAI,
|
||||
прикладів Ollama, обмежень пригадування та усунення несправностей.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -212,13 +213,13 @@ version походить зі старішого external package train. Вик
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — bundled browser Plugin для browser tool, `openclaw browser` CLI, `browser.request` gateway method, browser runtime і default browser control service (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — bridge VS Code Copilot Proxy (вимкнено за замовчуванням)
|
||||
- `browser` — вбудований browser-плагін для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, середовища виконання browser і стандартного сервісу керування browser (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні Plugins? Див. [Community Plugins](/uk/plugins/community).
|
||||
Шукаєте сторонні плагіни? Див. [Спільнотні плагіни](/uk/plugins/community).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -236,40 +237,40 @@ version походить зі старішого external package train. Вик
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Опис |
|
||||
| Поле | Опис |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `allow` | Plugin allowlist (необов’язково) |
|
||||
| `deny` | Plugin denylist (необов’язково; deny має пріоритет) |
|
||||
| `load.paths` | Додаткові plugin files/directories |
|
||||
| `slots` | Exclusive slot selectors (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі + конфігурація для окремого Plugin |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `allow` | Список дозволених плагінів (необов’язково) |
|
||||
| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги плагінів |
|
||||
| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі й конфігурація для окремого плагіна |
|
||||
|
||||
`plugins.allow` є exclusive. Коли він непорожній, завантажуватися
|
||||
або exposing tools можуть лише перелічені Plugins, навіть якщо `tools.allow` містить `"*"` або конкретну
|
||||
назву tool, що належить Plugin. Якщо tool allowlist посилається на plugin tools, додайте owning plugin ids
|
||||
`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися
|
||||
або відкривати інструменти можуть лише перелічені плагіни, навіть якщо `tools.allow` містить `"*"` або конкретну
|
||||
назву інструмента, що належить плагіну. Якщо список дозволених інструментів посилається на інструменти плагінів, додайте ідентифікатори плагінів-власників
|
||||
до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку
|
||||
форму.
|
||||
|
||||
Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway працює з config
|
||||
watch + in-process restart enabled (стандартний шлях `openclaw gateway`), цей
|
||||
restart зазвичай виконується автоматично за мить після запису config.
|
||||
Немає підтримуваного hot-reload path для native plugin runtime code або lifecycle
|
||||
hooks; перезапустіть процес Gateway, який обслуговує live channel, перш ніж
|
||||
очікувати виконання оновленого коду `register(api)`, hooks `api.on(...)`, tools, services або
|
||||
provider/runtime hooks.
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненим спостереженням за конфігурацією
|
||||
та перезапуском у процесі (стандартний шлях `openclaw gateway`), такий
|
||||
перезапуск зазвичай виконується автоматично за мить після запису конфігурації.
|
||||
Немає підтримуваного шляху гарячого перезавантаження для нативного коду середовища виконання плагіна або lifecycle-
|
||||
хуків; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж
|
||||
очікувати виконання оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, сервісів або
|
||||
provider/runtime-хуків.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок plugin registry/config. Позначка
|
||||
`enabled` для Plugin там означає, що persisted registry і поточна config дозволяють
|
||||
Plugin брати участь. Це не підтверджує, що вже запущений remote Gateway
|
||||
child перезапустився з тим самим plugin code. У VPS/container setups з
|
||||
wrapper processes надсилайте restarts до фактичного процесу `openclaw gateway run`
|
||||
`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Увімкнений
|
||||
там плагін означає, що збережений реєстр і поточна конфігурація дозволяють
|
||||
плагіну брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway
|
||||
перезапустився з тим самим кодом плагіна. У VPS/container-налаштуваннях із
|
||||
процесами-обгортками надсилайте перезапуски до фактичного процесу `openclaw gateway run`
|
||||
або використовуйте `openclaw gateway restart` проти запущеного Gateway.
|
||||
|
||||
<Accordion title="Стани Plugin: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
<Accordion title="Стани Plugin: вимкнений vs відсутній vs недійсний">
|
||||
- **Вимкнений**: plugin існує, але правила ввімкнення вимкнули його. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на id plugin, який виявлення не знайшло.
|
||||
- **Недійсний**: plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши його конфігураційне навантаження.
|
||||
- **Недійсний**: plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей plugin; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та видаливши його конфігураційне навантаження.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -279,9 +280,9 @@ OpenClaw сканує plugins у такому порядку (перший зб
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, які вказують
|
||||
назад на власні упаковані каталоги вбудованих plugin OpenClaw, ігноруються;
|
||||
запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми.
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують
|
||||
назад на власні упаковані каталоги bundled plugin OpenClaw, ігноруються;
|
||||
виконайте `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми.
|
||||
</Step>
|
||||
|
||||
<Step title="Plugins робочої області">
|
||||
@ -292,65 +293,65 @@ OpenClaw сканує plugins у такому порядку (перший зб
|
||||
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Вбудовані plugins">
|
||||
<Step title="Bundled plugins">
|
||||
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Упаковані інсталяції та образи Docker зазвичай розв’язують вбудовані plugins із
|
||||
скомпільованого дерева `dist/extensions`. Якщо каталог джерельного коду вбудованого plugin
|
||||
змонтовано поверх відповідного упакованого шляху до джерельного коду, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw трактує цей змонтований каталог джерельного коду
|
||||
як накладання вбудованого джерельного коду та виявляє його перед упакованим
|
||||
бандлом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних
|
||||
циклів супровідників без перемикання кожного вбудованого plugin назад на джерельний код TypeScript.
|
||||
Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-бандли
|
||||
навіть за наявності змонтованих накладань джерельного коду.
|
||||
Упаковані інсталяції та Docker-образи зазвичай розв’язують bundled plugins із
|
||||
скомпільованого дерева `dist/extensions`. Якщо каталог джерел bundled plugin
|
||||
змонтовано поверх відповідного упакованого шляху джерел, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований каталог джерел
|
||||
як overlay bundled source і виявляє його перед упакованим bundle
|
||||
`/app/dist/extensions/synology-chat`. Це зберігає робочими контейнерні
|
||||
цикли супровідників без повернення кожного bundled plugin до TypeScript-джерел.
|
||||
Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist bundles
|
||||
навіть за наявності змонтованих source overlay.
|
||||
|
||||
### Правила ввімкнення
|
||||
|
||||
- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження plugin
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.deny` завжди має перевагу над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей plugin
|
||||
- Plugins із робочої області **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані plugins дотримуються вбудованого набору ввімкнення за замовчуванням, якщо це не перевизначено
|
||||
- Bundled plugins дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний plugin для цього слота
|
||||
- Деякі вбудовані opt-in plugins автоматично вмикаються, коли конфігурація називає
|
||||
поверхню, що належить plugin, наприклад посилання на модель постачальника, конфігурацію каналу або середовище виконання
|
||||
- Деякі bundled opt-in plugins вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить plugin, наприклад посилання на модель постачальника, конфігурацію каналу або runtime
|
||||
harness
|
||||
- Застаріла конфігурація plugin зберігається, доки активний `plugins.enabled: false`;
|
||||
повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі id
|
||||
- Маршрути Codex родини OpenAI зберігають окремі межі plugin:
|
||||
`openai-codex/*` належить до plugin OpenAI, тоді як вбудований plugin сервера застосунку Codex
|
||||
вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
знову ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі ids
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі plugin:
|
||||
`openai-codex/*` належить OpenAI plugin, тоді як bundled Codex
|
||||
app-server plugin вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
посилання на моделі `codex/*`
|
||||
|
||||
## Усунення несправностей runtime hooks
|
||||
## Усунення проблем із runtime hooks
|
||||
|
||||
Якщо plugin з’являється в `plugins list`, але побічні ефекти або hooks `register(api)`
|
||||
не виконуються в живому чат-трафіку, спершу перевірте це:
|
||||
Якщо plugin з’являється в `plugins list`, але побічні ефекти `register(api)` або hooks
|
||||
не виконуються в живому трафіку чату, спочатку перевірте таке:
|
||||
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте.
|
||||
- Перезапустіть живий Gateway після змін інсталяції/config/code plugin. У контейнерах-обгортках
|
||||
PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
- Перезапустіть живий Gateway після змін інсталяції/config/code plugin. У wrapper
|
||||
containers PID 1 може бути лише supervisor; перезапустіть або надішліть сигнал дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використайте `openclaw plugins inspect <id> --runtime --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Невбудовані conversation hooks, як-от `llm_input`,
|
||||
діагностику. 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 і, під час налагодження payload постачальника, запускайте
|
||||
створить вивід assistant.
|
||||
- Для доказу ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні сесії/статусу Gateway і, під час налагодження provider payloads, запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
### Повільне налаштування інструментів plugin
|
||||
|
||||
Якщо здається, що ходи агента зависають під час підготовки інструментів, увімкніть trace-журналювання та
|
||||
перевірте рядки часу виконання фабрик інструментів plugin:
|
||||
Якщо ходи агента, здається, зависають під час підготовки інструментів, увімкніть trace logging і
|
||||
перевірте рядки часу виконання factory інструментів plugin:
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -363,22 +364,22 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
Підсумок перелічує загальний час фабрик і найповільніші фабрики інструментів plugin,
|
||||
включно з id plugin, оголошеними назвами інструментів, формою результату та тим, чи є інструмент
|
||||
необов’язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика триває
|
||||
щонайменше 1 с або загальна підготовка фабрик інструментів plugin триває щонайменше 5 с.
|
||||
Підсумок перелічує загальний час factory і найповільніші factories інструментів plugin,
|
||||
зокрема id plugin, оголошені назви інструментів, форму результату та чи є інструмент
|
||||
необов’язковим. Повільні рядки підвищуються до warnings, коли один factory займає
|
||||
щонайменше 1s або загальна підготовка factory інструментів plugin займає щонайменше 5s.
|
||||
|
||||
Якщо один plugin домінує за часом, перевірте його runtime-реєстрації:
|
||||
Якщо один plugin домінує в часі, перевірте його runtime registrations:
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
Потім оновіть, перевстановіть або вимкніть цей plugin. Автори Plugin повинні переносити
|
||||
Потім оновіть, перевстановіть або вимкніть цей plugin. Автори Plugin мають переносити
|
||||
дороге завантаження залежностей за шлях виконання інструмента, а не робити це
|
||||
всередині фабрики інструмента.
|
||||
всередині tool factory.
|
||||
|
||||
### Дублювання власника каналу або інструмента
|
||||
### Дублювання власності каналу або інструмента
|
||||
|
||||
Симптоми:
|
||||
|
||||
@ -386,35 +387,34 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
Це означає, що більш ніж один увімкнений plugin намагається володіти тим самим каналом,
|
||||
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній plugin каналу,
|
||||
установлений поруч із вбудованим plugin, який тепер надає той самий id каналу.
|
||||
Це означає, що більше ніж один увімкнений plugin намагається володіти тим самим каналом,
|
||||
setup flow або назвою інструмента. Найпоширеніша причина — зовнішній channel plugin,
|
||||
встановлений поруч із bundled plugin, який тепер надає той самий channel id.
|
||||
|
||||
Кроки налагодження:
|
||||
|
||||
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin
|
||||
і походження.
|
||||
- Запустіть `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного plugin і
|
||||
- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin
|
||||
і його походження.
|
||||
- Виконайте `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного plugin і
|
||||
порівняйте `channels`, `channelConfigs`, `tools` і діагностику.
|
||||
- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
- Виконайте `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
пакетів plugin, щоб збережені метадані відображали поточну інсталяцію.
|
||||
- Перезапустіть Gateway після змін інсталяції, реєстру або конфігурації.
|
||||
- Перезапустіть Gateway після змін інсталяції, registry або конфігурації.
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
- Якщо один plugin навмисно замінює інший для того самого id каналу, бажаний
|
||||
- Якщо один 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` або видаліть застарілу інсталяцію
|
||||
plugin.
|
||||
- Якщо дублювання випадкове, вимкніть одну сторону за допомогою
|
||||
`plugins.entries.<plugin-id>.enabled: false` або видаліть застарілу інсталяцію plugin.
|
||||
- Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і
|
||||
повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти,
|
||||
що належать plugin, щоб runtime-поверхня була однозначною.
|
||||
що належать plugin, щоб runtime surface була однозначною.
|
||||
|
||||
## Слоти Plugin (ексклюзивні категорії)
|
||||
|
||||
Деякі категорії є ексклюзивними (активна лише одна за раз):
|
||||
Деякі категорії є ексклюзивними (активною одночасно може бути лише одна):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -427,9 +427,9 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що він контролює | Типове значення |
|
||||
| Слот | Що він контролює | За замовчуванням |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | Plugin active memory | `memory-core` |
|
||||
| `memory` | Plugin активної пам’яті | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
|
||||
## Довідник CLI
|
||||
@ -479,56 +479,85 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Вбудовані plugins постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser
|
||||
plugin). Інші вбудовані plugins усе ще потребують `openclaw plugins enable <id>`.
|
||||
Bundled plugins постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад
|
||||
bundled model providers, bundled speech providers і bundled browser
|
||||
plugin). Інші bundled plugins усе ще потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний установлений plugin або hook pack на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для регулярних оновлень відстежуваних npm
|
||||
plugins. Він не підтримується з `--link`, який повторно використовує шлях до джерельного коду замість
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
plugins. Це не підтримується з `--link`, який повторно використовує шлях джерел замість
|
||||
копіювання поверх керованої цілі інсталяції.
|
||||
|
||||
Коли `plugins.allow` уже встановлено, `openclaw plugins install` додає
|
||||
id установленого plugin до цього allowlist перед його ввімкненням. Якщо той самий id plugin
|
||||
наявний у `plugins.deny`, інсталяція видаляє цей застарілий deny-запис, щоб
|
||||
явна інсталяція могла завантажуватися одразу після перезапуску.
|
||||
id встановленого plugin до цього allowlist перед увімкненням. Якщо той самий id plugin
|
||||
наявний у `plugins.deny`, install видаляє цей застарілий deny-запис, щоб
|
||||
явна інсталяція одразу завантажувалася після перезапуску.
|
||||
|
||||
OpenClaw підтримує збережений локальний реєстр plugin як модель холодного читання для
|
||||
OpenClaw зберігає постійний локальний registry plugin як cold read model для
|
||||
інвентарю plugin, власності внесків і планування запуску. Потоки install, update,
|
||||
uninstall, enable і disable оновлюють цей реєстр після зміни стану plugin.
|
||||
Той самий файл `plugins/installs.json` зберігає сталі метадані інсталяції в
|
||||
верхньорівневому `installRecords` і метадані маніфестів, які можна перебудувати, у `plugins`. Якщо
|
||||
реєстр відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його manifest view із записів інсталяцій, політики конфігурації та
|
||||
метаданих manifest/package без завантаження runtime-модулів plugin.
|
||||
uninstall, enable і disable оновлюють цей registry після зміни стану plugin.
|
||||
Той самий файл `plugins/installs.json` зберігає довговічні метадані інсталяції в
|
||||
верхньорівневому `installRecords` і перебудовувані manifest metadata в `plugins`. Якщо
|
||||
registry відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його manifest view із записів інсталяції, config policy і
|
||||
metadata manifest/package без завантаження runtime modules plugin.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних інсталяцій. Передавання
|
||||
специфікації npm-пакета з dist-tag або точною версією розв’язує назву пакета
|
||||
назад до відстежуваного запису plugin і записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії повертає точно закріплену інсталяцію назад до
|
||||
типової лінії випуску реєстру. Якщо встановлений npm plugin уже відповідає
|
||||
npm package spec із dist-tag або точною версією розв’язує назву пакета
|
||||
назад до відстежуваного запису plugin і записує нову spec для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переміщує точну закріплену інсталяцію назад до
|
||||
стандартної release line registry. Якщо встановлений npm plugin уже відповідає
|
||||
розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або перезапису конфігурації.
|
||||
без завантаження, перевстановлення або переписування конфігурації.
|
||||
|
||||
`--pin` доступний лише для npm. Він не підтримується з `--marketplace`, оскільки
|
||||
marketplace-інсталяції зберігають метадані джерела marketplace замість npm-специфікації.
|
||||
`--pin` підтримується лише для npm. Він не підтримується з `--marketplace`, оскільки
|
||||
marketplace installs зберігають metadata marketplace source замість npm spec.
|
||||
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних спрацювань вбудованого сканера небезпечного коду. Воно дає змогу встановленням плагінів і оновленням плагінів продовжуватися попри вбудовані знахідки рівня `critical`, але все одно не обходить блокування політики плагіна `before_install` або блокування через збій сканування. Сканування під час встановлення ігнорують поширені тестові файли й каталоги, як-от `tests/`, `__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки; оголошені runtime-точки входу плагіна все одно скануються, навіть якщо використовують одну з цих назв.
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє продовжувати
|
||||
встановлення Plugin і оновлення Plugin попри вбудовані знахідки рівня
|
||||
`critical`, але все одно не обходить блокування політик Plugin `before_install`
|
||||
або блокування через збій сканування. Сканування встановлення ігнорує поширені
|
||||
тестові файли й каталоги, як-от `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 пакетів, командні Skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошених у маніфесті `lspServers`, командні Skills Cursor, а також сумісні каталоги хуків Codex.
|
||||
Сумісні пакети беруть участь у тому самому потоці списку/перегляду/увімкнення/вимкнення
|
||||
Plugin. Поточна підтримка runtime охоплює пакетні Skills, командні Skills Claude,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
|
||||
оголошені в маніфесті типові значення `lspServers`, командні Skills Cursor і
|
||||
сумісні каталоги хуків Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості пакета, а також підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості пакета, а
|
||||
також підтримувані або непідтримувані записи серверів MCP і LSP для Plugin на
|
||||
основі пакетів.
|
||||
|
||||
Джерелами marketplace можуть бути відома назва marketplace Claude з `~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях `marketplace.json`, GitHub-скорочення на кшталт `owner/repo`, URL репозиторію GitHub або git URL. Для віддалених marketplace записи плагінів мають залишатися всередині клонованого репозиторію marketplace і використовувати лише джерела з відносними шляхами.
|
||||
Джерелами маркетплейсу можуть бути назва відомого маркетплейсу Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, корінь локального маркетплейсу або
|
||||
шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL
|
||||
репозиторію GitHub або git URL. Для віддалених маркетплейсів записи Plugin мають
|
||||
залишатися всередині клонованого репозиторію маркетплейсу й використовувати лише
|
||||
джерела з відносними шляхами.
|
||||
|
||||
Дивіться [довідник CLI `openclaw plugins`](/uk/cli/plugins), щоб отримати повні подробиці.
|
||||
Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
|
||||
## Огляд API Plugin
|
||||
|
||||
Нативні плагіни експортують об'єкт входу, який надає `register(api)`. Старіші плагіни можуть усе ще використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають використовувати `register`.
|
||||
Нативні Plugin експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
Plugin можуть усе ще використовувати `activate(api)` як застарілий псевдонім,
|
||||
але нові Plugin мають використовувати `register`.
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -548,60 +577,76 @@ 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. |
|
||||
|
||||
Входи плагінів, які відкривають сокети, бази даних, фонові worker-и або довгоживучі клієнти, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`. Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють запущений реєстр Gateway. Виявлення не активує, але не є вільним від імпорту: OpenClaw може виконати довірений вхід плагіна або модуль канального плагіна, щоб побудувати знімок. Тримайте верхні рівні модулів легковаговими й без побічних ефектів, а мережеві клієнти, subprocess-и, слухачі, читання облікових даних і запуск сервісів переміщуйте за шляхи full-runtime.
|
||||
Записи Plugin, які відкривають сокети, бази даних, фонові воркери або
|
||||
довготривалі клієнти, мають захищати ці побічні ефекти перевіркою
|
||||
`api.registrationMode === "full"`. Завантаження виявлення кешуються окремо від
|
||||
активаційних завантажень і не замінюють запущений реєстр Gateway. Виявлення є
|
||||
неактиваційним, але не без імпорту: OpenClaw може виконати довірений запис
|
||||
Plugin або модуль Plugin каналу, щоб побудувати знімок. Тримайте верхні рівні
|
||||
модулів легкими й без побічних ефектів, а мережеві клієнти, підпроцеси,
|
||||
слухачі, читання облікових даних і запуск сервісів переносьте за шляхи повного
|
||||
runtime.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | ---------------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Streaming STT |
|
||||
| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Провайдер web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фоновий сервіс |
|
||||
| Метод | Що реєструє |
|
||||
| --------------------------------------- | ----------------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
|
||||
| `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 }` є no-op і не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` є no-op і не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` є no-op і не скасовує попереднє скасування.
|
||||
- `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 }` не виконує дії й не скасовує попереднє скасування.
|
||||
|
||||
Нативний Codex app-server передає події нативних інструментів Codex назад у цю поверхню хуків через bridge. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex `PermissionRequest`. Bridge поки що не переписує аргументи нативних інструментів Codex. Точна межа runtime-підтримки Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
|
||||
Нативний сервер застосунку Codex передає нативні події інструментів 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).
|
||||
Повну поведінку типізованих хуків див. в [огляді 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/architecture) — модель можливостей і pipeline завантаження
|
||||
- [Плагіни спільноти](/uk/plugins/community) — списки від сторонніх розробників
|
||||
- [Створення 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user