diff --git a/docs/uk/gateway/logging.md b/docs/uk/gateway/logging.md index 6a2d27040..eca2deed9 100644 --- a/docs/uk/gateway/logging.md +++ b/docs/uk/gateway/logging.md @@ -1,81 +1,84 @@ --- read_when: - - Зміна виводу або форматів логування + - Зміна виводу журналювання або форматів - Налагодження виводу CLI або Gateway -summary: Інтерфейси журналювання, файлові журнали, стилі журналів WS і форматування консолі +summary: Поверхні логування, файлові логи, стилі WS-логів і форматування консолі title: Журналювання Gateway x-i18n: - generated_at: "2026-05-01T05:53:12Z" + generated_at: "2026-05-01T22:18:30Z" model: gpt-5.5 provider: openai - source_hash: f843812a41c25f9ca1884543ad3a5663c8e0bc327027cbd2b58ea6557c466aa9 + source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13 source_path: gateway/logging.md workflow: 16 --- # Журналювання -Огляд для користувачів (CLI + інтерфейс керування + конфігурація) див. у [/logging](/uk/logging). +Огляд для користувачів (CLI + Control UI + конфігурація) див. у [/logging](/uk/logging). -OpenClaw має дві “поверхні” журналів: +OpenClaw має дві «поверхні» журналювання: -- **Вивід у консоль** (те, що ви бачите в терміналі / інтерфейсі налагодження). -- **Файлові журнали** (рядки JSON), які записує логер Gateway. +- **Консольний вивід** (те, що ви бачите в терміналі / Debug UI). +- **Файлові журнали** (рядки JSON), які записує журналювач Gateway. -## Файловий логер +## Файловий журналювач -- Типовий ротаційний файл журналу розташований у `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log` +- Стандартний ротаційний файл журналу розташований у `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log` - Дата використовує локальний часовий пояс хоста Gateway. -- Активні файли журналу ротуються при `logging.maxFileBytes` (типово: 100 МБ), зберігаючи - до п’яти нумерованих архівів і продовжуючи запис у новий активний файл. -- Шлях до файла журналу та рівень можна налаштувати через `~/.openclaw/openclaw.json`: +- Активні файли журналу ротуються при `logging.maxFileBytes` (стандартно: 100 MB), зберігаючи + до п’яти пронумерованих архівів і продовжуючи запис у новий активний файл. +- Шлях до файлу журналу та рівень можна налаштувати через `~/.openclaw/openclaw.json`: - `logging.file` - `logging.level` -Формат файла — один об’єкт JSON на рядок. +Формат файлу: один об’єкт JSON на рядок. -Вкладка журналів інтерфейсу керування стежить за цим файлом через Gateway (`logs.tail`). +Вкладка журналів у Control UI відстежує цей файл через Gateway (`logs.tail`). CLI може робити те саме: ```bash openclaw logs --follow ``` -**Докладність проти рівнів журналювання** +**Детальний режим і рівні журналювання** - **Файлові журнали** керуються виключно `logging.level`. -- `--verbose` впливає лише на **докладність консолі** (і стиль журналів WS); він **не** - підвищує рівень файлового журналювання. -- Щоб записувати у файлові журнали деталі, доступні лише в докладному режимі, установіть `logging.level` у `debug` або +- `--verbose` впливає лише на **детальність консолі** (і стиль журналів WS); він **не** + підвищує рівень файлового журналу. +- Щоб записувати у файлові журнали деталі, доступні лише в детальному режимі, установіть `logging.level` на `debug` або `trace`. +- Журналювання trace також включає діагностичні підсумки часу для вибраних гарячих шляхів, + наприклад підготовки фабрики інструментів Plugin. Див. + [/tools/plugin#slow-plugin-tool-setup](/uk/tools/plugin#slow-plugin-tool-setup). -## Перехоплення консолі +## Захоплення консолі -CLI перехоплює `console.log/info/warn/error/debug/trace` і записує їх у файлові журнали, -водночас продовжуючи друкувати у stdout/stderr. +CLI захоплює `console.log/info/warn/error/debug/trace` і записує їх у файлові журнали, +одночасно продовжуючи друкувати у stdout/stderr. -Докладність консолі можна налаштувати незалежно через: +Детальність консолі можна налаштовувати незалежно через: -- `logging.consoleLevel` (типово `info`) +- `logging.consoleLevel` (стандартно `info`) - `logging.consoleStyle` (`pretty` | `compact` | `json`) -## Редагування секретів +## Редагування чутливих даних -OpenClaw може маскувати чутливі токени до того, як вивід журналу або транскрипта залишить -процес. Ця політика редагування журналів застосовується до консолі, файлового журналу, записів журналу OTLP -і текстових приймачів транскриптів сесій, тому відповідні секретні значення +OpenClaw може маскувати чутливі токени до того, як журнальний або транскриптний вивід залишить +процес. Ця політика редагування журналів застосовується до консолі, файлового журналу, OTLP +записів журналу та текстових приймачів транскриптів сесії, тому відповідні секретні значення маскуються до запису рядків JSONL або повідомлень на диск. -- `logging.redactSensitive`: `off` | `tools` (типово: `tools`) -- `logging.redactPatterns`: масив рядків регулярних виразів (перевизначає типові значення) - - Використовуйте необроблені рядки регулярних виразів (автоматично `gi`) або `/pattern/flags`, якщо потрібні власні прапорці. +- `logging.redactSensitive`: `off` | `tools` (стандартно: `tools`) +- `logging.redactPatterns`: масив рядків regex (перевизначає стандартні значення) + - Використовуйте сирі рядки regex (авто `gi`) або `/pattern/flags`, якщо потрібні власні прапорці. - Збіги маскуються зі збереженням перших 6 + останніх 4 символів (довжина >= 18), інакше `***`. - - Типові значення покривають поширені присвоєння ключів, прапорці CLI, поля JSON, bearer-заголовки, блоки PEM, популярні префікси токенів і назви полів платіжних облікових даних, як-от номер картки, CVC/CVV, спільний платіжний токен і платіжні облікові дані. + - Стандартні значення покривають поширені присвоєння ключів, CLI прапорці, поля JSON, bearer-заголовки, блоки PEM, популярні префікси токенів і назви полів платіжних облікових даних, як-от номер картки, CVC/CVV, спільний платіжний токен і платіжні облікові дані. -Деякі межі безпеки завжди редагують секрети незалежно від `logging.redactSensitive`. -Сюди входять події викликів інструментів інтерфейсу керування, вивід інструмента `sessions_history`, -експорти підтримки діагностики, спостереження помилок провайдерів, показ команди схвалення exec -і журнали протоколу Gateway WebSocket. Ці поверхні все ще можуть використовувати +Деякі межі безпеки завжди редагують чутливі дані незалежно від `logging.redactSensitive`. +Сюди входять події викликів інструментів Control UI, вивід інструмента `sessions_history`, +експорти діагностичної підтримки, спостереження помилок провайдерів, відображення команди +схвалення exec і журнали протоколу Gateway WebSocket. Ці поверхні все ще можуть використовувати `logging.redactPatterns` як додаткові шаблони, але `redactSensitive: "off"` не змушує їх виводити необроблені секрети. @@ -83,19 +86,19 @@ OpenClaw може маскувати чутливі токени до того, Gateway друкує журнали протоколу WebSocket у двох режимах: -- **Звичайний режим (без `--verbose`)**: друкуються лише “цікаві” результати RPC: +- **Звичайний режим (без `--verbose`)**: друкуються лише «цікаві» результати RPC: - помилки (`ok=false`) - - повільні виклики (типовий поріг: `>= 50ms`) + - повільні виклики (стандартний поріг: `>= 50ms`) - помилки розбору -- **Докладний режим (`--verbose`)**: друкує весь трафік запитів/відповідей WS. +- **Детальний режим (`--verbose`)**: друкує весь трафік запитів/відповідей WS. ### Стиль журналів WS -`openclaw gateway` підтримує перемикач стилю для кожного Gateway: +`openclaw gateway` підтримує перемикач стилю для окремого Gateway: -- `--ws-log auto` (типово): звичайний режим оптимізований; докладний режим використовує компактний вивід -- `--ws-log compact`: компактний вивід (парні запит/відповідь) у докладному режимі -- `--ws-log full`: повний вивід для кожного фрейму в докладному режимі +- `--ws-log auto` (стандартно): звичайний режим оптимізований; детальний режим використовує компактний вивід +- `--ws-log compact`: компактний вивід (парні запит/відповідь) у детальному режимі +- `--ws-log full`: повний вивід для кожного кадру в детальному режимі - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -114,21 +117,21 @@ openclaw gateway --verbose --ws-log full ## Форматування консолі (журналювання підсистем) Форматер консолі **враховує TTY** і друкує узгоджені рядки з префіксами. -Логери підсистем групують вивід і роблять його зручним для перегляду. +Журналювачі підсистем зберігають вивід згрупованим і зручним для перегляду. Поведінка: - **Префікси підсистем** у кожному рядку (наприклад, `[gateway]`, `[canvas]`, `[tailscale]`) - **Кольори підсистем** (стабільні для кожної підсистеми) плюс забарвлення рівнів -- **Колір, коли вивід є TTY або середовище схоже на розширений термінал** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), з урахуванням `NO_COLOR` -- **Скорочені префікси підсистем**: відкидає початкові `gateway/` + `channels/`, залишає останні 2 сегменти (наприклад, `whatsapp/outbound`) -- **Підлогери за підсистемами** (автоматичний префікс + структуроване поле `{ subsystem }`) -- **`logRaw()`** для виводу QR/UX (без префікса, без форматування) +- **Колір, коли вивід є TTY або середовище схоже на насичений термінал** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), враховує `NO_COLOR` +- **Скорочені префікси підсистем**: прибирає початкові `gateway/` + `channels/`, залишає останні 2 сегменти (наприклад, `whatsapp/outbound`) +- **Піджурналювачі за підсистемою** (автопрефікс + структуроване поле `{ subsystem }`) +- **`logRaw()`** для QR/UX виводу (без префікса, без форматування) - **Стилі консолі** (наприклад, `pretty | compact | json`) -- **Рівень журналювання консолі** окремий від рівня файлового журналювання (файл зберігає повну деталізацію, коли `logging.level` установлено в `debug`/`trace`) -- **Тіла повідомлень WhatsApp** журналюються на рівні `debug` (використовуйте `--verbose`, щоб їх побачити) +- **Рівень журналювання консолі** окремий від рівня файлового журналу (файл зберігає повну деталізацію, коли `logging.level` встановлено на `debug`/`trace`) +- **Тіла повідомлень WhatsApp** журналюються на рівні `debug` (використовуйте `--verbose`, щоб їх бачити) -Це зберігає стабільність наявних файлових журналів і водночас робить інтерактивний вивід зручним для перегляду. +Це зберігає наявні файлові журнали стабільними, водночас роблячи інтерактивний вивід зручним для перегляду. ## Пов’язане diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index e89334142..4f1cdbeca 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -4,22 +4,22 @@ read_when: - Розуміння правил виявлення та завантаження Plugin - Робота з пакетами Plugin, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлення, налаштування та керування Plugin OpenClaw +summary: Встановлення, налаштування та керування плагінами OpenClaw title: Plugins x-i18n: - generated_at: "2026-05-01T21:40:38Z" + generated_at: "2026-05-01T22:18:46Z" model: gpt-5.5 provider: openai - source_hash: 0dbb4d0102f3f2060fe13aa5e6ae1b24080a456f223e985ccfa390106e94f4d8 + source_hash: 45d4804c55d70000cf471d9d258204ef0028c30d5a731750c37f5d40991b72a0 source_path: tools/plugin.md workflow: 16 --- -Plugin-и розширюють OpenClaw новими можливостями: каналами, провайдерами моделей, -обв’язками агентів, інструментами, Skills, мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, отриманням вебвмісту, вебпошуком -і не тільки. Деякі Plugin-и є **core** (постачаються з OpenClaw), інші -є **зовнішніми**. Більшість зовнішніх Plugin-ів публікуються й знаходяться через -[ClawHub](/uk/tools/clawhub). Npm і надалі підтримується для прямих встановлень і для +Plugin-и розширюють OpenClaw новими можливостями: каналами, постачальниками моделей, +обгортками агентів, інструментами, Skills, мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, web fetch, web +search тощо. Деякі Plugin-и є **основними** (постачаються з OpenClaw), інші +є **зовнішніми**. Більшість зовнішніх Plugin-ів публікуються й виявляються через +[ClawHub](/uk/tools/clawhub). Npm лишається підтримуваним для прямих встановлень і для тимчасового набору пакетів Plugin-ів, що належать OpenClaw, доки ця міграція завершується. ## Швидкий старт @@ -31,7 +31,7 @@ Plugin-и розширюють OpenClaw новими можливостями: ``` - + ```bash # From npm openclaw plugins install npm:@acme/openclaw-plugin @@ -51,7 +51,7 @@ Plugin-и розширюють OpenClaw новими можливостями: openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. + Потім налаштуйте в `plugins.entries.\.config` у вашому конфігураційному файлі. @@ -63,14 +63,14 @@ Plugin-и розширюють OpenClaw новими можливостями: openclaw --help ``` - Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, сервіси, gateway - методи, хуки або CLI-команди, що належать Plugin-у. Звичайний `inspect` — це холодна - перевірка маніфесту/реєстру, яка навмисно уникає імпортування runtime Plugin-а. + Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, служби, методи Gateway, + хуки або CLI-команди, що належать Plugin-у. Звичайний `inspect` є холодною + перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime Plugin-а. -Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню, природному для чату, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub: @@ -78,33 +78,35 @@ Plugin-и розширюють OpenClaw новими можливостями: /plugin enable ``` -Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний -`clawhub:`, явний `npm:`, явний `git:` або просту специфікацію пакета -(спочатку ClawHub, потім резервно npm). +Шлях встановлення використовує той самий resolver, що й CLI: локальний шлях/архів, явний +`clawhub:`, явний `npm:`, явний `git:` або специфікація пакета +без префікса (спочатку ClawHub, потім fallback до npm). -Якщо конфігурація недійсна, встановлення зазвичай завершується без змін і спрямовує вас до -`openclaw doctor --fix`. Єдиний виняток відновлення — вузький шлях перевстановлення вбудованого Plugin-а для Plugin-ів, які увімкнули +Якщо конфігурація недійсна, встановлення зазвичай завершується закритою відмовою та спрямовує вас до +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях +повторного встановлення bundled-plugin для Plugin-ів, які ввімкнули `openclaw.install.allowInvalidConfigRecovery`. Під час запуску Gateway недійсна конфігурація одного Plugin-а ізолюється до цього Plugin-а: -запуск журналює проблему `plugins.entries..config`, пропускає цей Plugin під час -завантаження та залишає інші Plugin-и й канали онлайн. Запустіть `openclaw doctor --fix`, -щоб помістити проблемну конфігурацію Plugin-а в карантин, вимкнувши цей запис Plugin-а й вилучивши +запуск записує проблему `plugins.entries..config` у журнали, пропускає цей Plugin під час +завантаження й залишає інші Plugin-и та канали онлайн. Запустіть `openclaw doctor --fix`, +щоб помістити погану конфігурацію Plugin-а в карантин, вимкнувши цей запис Plugin-а та видаливши його недійсний конфігураційний payload; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на Plugin, який більше не виявляється, але той самий застарілий id Plugin-а залишається в конфігурації Plugin-ів або записах встановлення, запуск Gateway -журналює попередження й пропускає цей канал замість блокування всіх інших каналів. -Запустіть `openclaw doctor --fix`, щоб вилучити застарілі записи каналу/Plugin-а; невідомі -ключі каналів без ознак застарілого Plugin-а й надалі не проходять валідацію, щоб друкарські помилки залишалися -помітними. -Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugin-и вважаються інертними: -запуск Gateway пропускає виявлення/завантаження Plugin-ів, а `openclaw doctor` зберігає -вимкнену конфігурацію Plugin-ів замість автоматичного вилучення. Знову ввімкніть Plugin-и перед -запуском очищення doctor, якщо хочете вилучити застарілі id Plugin-ів. +Коли конфігурація каналу посилається на Plugin, який більше не виявляється, але той самий +застарілий id Plugin-а лишається в конфігурації Plugin-а або записах встановлення, запуск Gateway +записує попередження й пропускає цей канал замість блокування всіх інших каналів. +Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/Plugin-а; невідомі +ключі каналів без доказів застарілого Plugin-а все одно не проходять валідацію, щоб друкарські помилки лишалися +видимими. +Якщо задано `plugins.enabled: false`, застарілі посилання на Plugin-и трактуються як інертні: +запуск Gateway пропускає роботу з виявлення/завантаження Plugin-ів, а `openclaw doctor` зберігає +вимкнену конфігурацію Plugin-а замість автоматичного видалення. Повторно увімкніть Plugin-и перед +запуском очищення doctor, якщо хочете видалити застарілі id Plugin-ів. -Встановлення залежностей Plugin-а відбувається лише під час явних потоків install/update або -doctor repair. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція не -запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні Plugin-и вже повинні -мати встановлені залежності, тоді як npm, git і ClawHub Plugin-и -встановлюються в керовані корені Plugin-ів OpenClaw із локальними для пакета +Встановлення залежностей Plugin-а відбувається лише під час явного встановлення/оновлення або +потоків ремонту doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція не +запускають пакетні менеджери й не ремонтують дерева залежностей. Локальні Plugin-и вже мають +мати встановлені залежності, тоді як npm-, git- і ClawHub-Plugin-и +встановлюються в керованих OpenClaw коренях Plugin-ів із локальними для пакета залежностями. Зовнішні Plugin-и та власні шляхи завантаження все одно потрібно встановлювати через `openclaw plugins install`. Див. [Розв’язання залежностей Plugin-а](/uk/plugins/dependency-resolution) щодо @@ -116,27 +118,27 @@ OpenClaw розпізнає два формати Plugin-ів: | Формат | Як це працює | Приклади | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні Plugin-и, community npm-пакети | -| **Bundle** | Макет, сумісний із Codex/Claude/Cursor; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні Plugin-и, 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-ів](/uk/plugins/bundles) для подробиць про bundle. -Якщо ви пишете native Plugin, почніть із [Створення Plugin-ів](/uk/plugins/building-plugins) +Якщо ви пишете native Plugin, почніть зі [Створення Plugin-ів](/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`. +Кожен запис має лишатися всередині каталогу пакета й розв’язуватися в читабельний +runtime-файл або у вихідний TypeScript-файл з інферованим зібраним JavaScript +peer, наприклад `src/index.ts` до `dist/index.js`. Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за -тими самими шляхами, що й вихідні записи. За наявності `runtimeExtensions` має містити -рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення та -виявлення Plugin-а замість тихого відкату до шляхів вихідного коду. Якщо ви також -публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його побудованого -JavaScript-відповідника; цей файл є обов’язковим, якщо оголошений. +тими самими шляхами, що й вихідні записи. Якщо присутній, `runtimeExtensions` має містити +рівно один запис для кожного запису `extensions`. Невідповідні списки спричиняють помилку встановлення та +виявлення Plugin-а замість мовчазного fallback до шляхів джерел. Якщо ви також +публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його зібраного +JavaScript peer; цей файл є обов’язковим, коли оголошений. ```json { @@ -153,14 +155,14 @@ JavaScript-відповідника; цей файл є обов’язкови ### Npm-пакети, що належать OpenClaw, під час міграції ClawHub є основним шляхом розповсюдження для більшості Plugin-ів. Поточні пакетовані -релізи OpenClaw вже містять багато офіційних Plugin-ів, тож вони не потребують +релізи OpenClaw уже містять багато офіційних Plugin-ів, тож вони не потребують окремих npm-встановлень у звичайних налаштуваннях. Доки кожен Plugin, що належить OpenClaw, не -мігрував до ClawHub, OpenClaw і надалі постачає деякі пакети Plugin-ів `@openclaw/*` в +мігрував до ClawHub, OpenClaw все ще постачає деякі пакети Plugin-ів `@openclaw/*` на npm для старіших/власних встановлень і прямих npm-процесів. -Якщо npm повідомляє, що пакет Plugin-а `@openclaw/*` застарілий, ця версія пакета -походить зі старішої зовнішньої лінійки пакетів. Використовуйте вбудований Plugin із -поточного OpenClaw або локальний checkout, доки новіший npm-пакет не буде опубліковано. +Якщо npm повідомляє, що пакет Plugin-а `@openclaw/*` є deprecated, ця версія пакета +походить зі старішої зовнішньої лінійки пакетів. Використовуйте bundled Plugin з +поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. | Plugin | Пакет | Документація | | --------------- | -------------------------- | ------------------------------------------ | @@ -178,10 +180,10 @@ npm для старіших/власних встановлень і прями | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачається з OpenClaw) +### Основні (постачаються з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -189,27 +191,27 @@ npm для старіших/власних встановлень і прями `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — вбудований пошук memory (за замовчуванням через `plugins.slots.memory`) - - `memory-lancedb` — довготривала memory на базі LanceDB з auto-recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`) + + - `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 і усунення несправностей. - + `elevenlabs`, `microsoft` - - `browser` — вбудований browser Plugin для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартного сервісу керування браузером (увімкнено за замовчуванням; вимкніть перед заміною) + - `browser` — bundled Plugin браузера для інструмента браузера, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime і стандартної служби керування браузером (увімкнено за замовчуванням; вимкніть перед заміною) - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням) -Шукаєте сторонні Plugin-и? Див. [Community Plugins](/uk/plugins/community). +Шукаєте сторонні Plugin-и? Див. [Plugin-и спільноти](/uk/plugins/community). ## Конфігурація @@ -232,50 +234,50 @@ npm для старіших/власних встановлень і прями | `enabled` | Головний перемикач (за замовчуванням: `true`) | | `allow` | Allowlist Plugin-ів (необов’язково) | | `deny` | Denylist Plugin-ів (необов’язково; deny має пріоритет) | -| `load.paths` | Додаткові файли/директорії Plugin-ів | +| `load.paths` | Додаткові файли/каталоги Plugin-ів | | `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | | `entries.\` | Перемикачі + конфігурація для окремого Plugin-а | `plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися або -надавати інструменти можуть лише перелічені Plugin-и, навіть якщо `tools.allow` містить `"*"` або конкретну назву -інструмента, що належить Plugin-у. Якщо allowlist інструментів посилається на інструменти Plugin-ів, додайте id Plugin-ів-власників -до `plugins.allow` або вилучіть `plugins.allow`; `openclaw doctor` попереджає про таку +експонувати інструменти можуть лише перелічені Plugin-и, навіть якщо `tools.allow` містить `"*"` або конкретну назву +інструмента, що належить Plugin-у. Якщо allowlist інструментів посилається на інструменти Plugin-а, додайте id Plugin-ів-власників +до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку форму. -Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими config -watch + in-process restart (стандартний шлях `openclaw gateway`), такий -перезапуск зазвичай виконується автоматично за мить після запису конфігурації. -Немає підтримуваного шляху hot-reload для runtime-коду native Plugin-а або lifecycle -hooks; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж -очікувати запуску оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, сервісів або -provider/runtime hooks. +Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з config +watch + in-process restart увімкненими (стандартний шлях `openclaw gateway`), цей +перезапуск зазвичай виконується автоматично через мить після запису конфігурації. +Підтримуваного шляху hot-reload для runtime-коду native Plugin-а або lifecycle +хуків немає; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж +очікувати виконання оновленого коду `register(api)`, хуків `api.on(...)`, інструментів, служб або +provider/runtime хуків. -`openclaw plugins list` — це локальний snapshot реєстру/конфігурації Plugin-ів. Plugin зі станом +`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin-ів. Plugin зі статусом `enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють Plugin-у брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway -перезапустився з тим самим кодом Plugin-а. У налаштуваннях VPS/контейнерів із -процесами-обгортками надсилайте перезапуски фактичному процесу `openclaw gateway run` -або використовуйте `openclaw gateway restart` для запущеного Gateway. +перезапустився з тим самим кодом Plugin-а. У налаштуваннях VPS/контейнерів з +wrapper-процесами надсилайте перезапуски фактичному процесу `openclaw gateway run`, +або використовуйте `openclaw gateway restart` проти запущеного Gateway. - + - **Вимкнений**: Plugin існує, але правила ввімкнення вимкнули його. Конфігурація зберігається. - - **Відсутній**: конфігурація посилається на id Plugin-а, який discovery не знайшов. - - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його й вилучивши його конфігураційний payload. + - **Відсутній**: конфігурація посилається на id Plugin-а, який виявлення не знайшло. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши його конфігураційний payload. -## Виявлення та пріоритетність +## Виявлення та пріоритет -OpenClaw сканує plugins у такому порядку (перше співпадіння перемагає): +OpenClaw сканує plugins у такому порядку (перша відповідність перемагає): - `plugins.load.paths` — явні шляхи до файлів або директорій. Шляхи, що вказують - назад на власні упаковані директорії bundled plugin OpenClaw, ігноруються; + `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують + назад на власні упаковані каталоги bundled plugin OpenClaw, ігноруються; запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. @@ -284,59 +286,91 @@ OpenClaw сканує plugins у такому порядку (перше спі - Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). + Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення). Інші потребують явного ввімкнення. -Упаковані встановлення та Docker-образи зазвичай розв’язують bundled plugins з -скомпільованого дерева `dist/extensions`. Якщо директорію джерел bundled plugin -змонтовано bind mount поверх відповідного упакованого шляху джерел, наприклад -`/app/extensions/synology-chat`, OpenClaw розглядає цю змонтовану директорію -джерел як bundled source overlay і виявляє її перед упакованим бандлом +Упаковані встановлення та Docker-образи зазвичай розв’язують bundled plugins із +скомпільованого дерева `dist/extensions`. Якщо каталог вихідного коду bundled plugin +підмонтовано поверх відповідного упакованого шляху до вихідного коду, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований каталог вихідного коду +як накладення bundled source і виявляє його перед упакованим bundle `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних -циклів супровідників без перемикання кожного bundled plugin назад на джерела TypeScript. -Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово -використовувати упаковані dist-бандли, навіть коли наявні source overlay mounts. +циклів мейнтейнерів без перемикання кожного bundled plugin назад на вихідний код TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist bundles +навіть за наявності змонтованих накладень вихідного коду. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі plugins і пропускає роботу виявлення/завантаження Plugin +- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження plugins - `plugins.deny` завжди має пріоритет над allow -- `plugins.entries.\.enabled: false` вимикає цей Plugin -- Plugins з походженням workspace **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) -- Bundled plugins дотримуються вбудованого набору default-on, якщо його не перевизначено -- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота +- `plugins.entries.\.enabled: false` вимикає цей plugin +- Plugins із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Bundled plugins дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено +- Ексклюзивні слоти можуть примусово ввімкнути вибраний plugin для цього слота - Деякі bundled opt-in plugins вмикаються автоматично, коли конфігурація називає - surface, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або runtime harness -- Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`; - повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі id -- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: + поверхню, що належить plugin, наприклад посилання на модель провайдера, конфігурацію каналу або runtime + harness +- Застаріла конфігурація plugin зберігається, доки активний `plugins.enabled: false`; + знову ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі ids +- Маршрути Codex сімейства OpenAI зберігають окремі межі plugin: `openai-codex/*` належить OpenAI plugin, тоді як bundled Codex - app-server plugin вибирається через `agentRuntime.id: "codex"` або legacy + app-server plugin вибирається через `agentRuntime.id: "codex"` або застарілі посилання на моделі `codex/*` ## Усунення несправностей runtime hooks -Якщо Plugin з’являється у `plugins list`, але побічні ефекти або hooks -`register(api)` не запускаються в live chat traffic, спочатку перевірте це: +Якщо plugin з’являється в `plugins list`, але побічні ефекти або hooks +`register(api)` не виконуються в живому чат-трафіку, спершу перевірте таке: - Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте. -- Перезапустіть live Gateway після змін встановлення/конфігурації/коду Plugin. У wrapper - containers PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому +- Перезапустіть живий Gateway після змін встановлення/config/code plugin. У wrapper + containers PID 1 може бути лише supervisor; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використовуйте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hooks і - діагностику. Non-bundled conversation hooks, як-от `llm_input`, +- Використайте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hooks і + діагностику. Небандловані conversation hooks, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`, потребують `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед - розв’язанням моделі для agent turns; `llm_output` запускається лише після того, як спроба моделі - створить assistant output. -- Для підтвердження фактичної моделі сесії використовуйте `openclaw sessions` або - поверхні сесії/статусу Gateway, а під час налагодження provider payloads запускайте +- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед розв’язанням моделі + для ходів агента; `llm_output` виконується лише після того, як спроба моделі + створює вивід асистента. +- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або + поверхні сесії/статусу Gateway, а під час налагодження payloads провайдера запускайте Gateway з `--raw-stream --raw-stream-path `. +### Повільне налаштування інструментів plugin + +Якщо ходи агента наче зависають під час підготовки інструментів, увімкніть trace logging і +перевірте рядки часу виконання factory інструментів plugin: + +```bash +openclaw config set logging.level trace +openclaw logs --follow +``` + +Шукайте: + +```text +[trace:plugin-tools] factory timings ... +``` + +Зведення перелічує загальний час factory і найповільніші factory інструментів plugin, +зокрема plugin id, оголошені назви інструментів, форму результату та чи є інструмент +необов’язковим. Повільні рядки підвищуються до попереджень, коли одна factory триває +щонайменше 1 с або загальна підготовка factory інструментів plugin триває щонайменше 5 с. + +Якщо один plugin домінує в часі виконання, перевірте його runtime registrations: + +```bash +openclaw plugins inspect --runtime --json +``` + +Потім оновіть, перевстановіть або вимкніть цей plugin. Автори Plugin повинні переносити +дороге завантаження залежностей за шлях виконання інструмента, а не виконувати його +всередині tool factory. + ### Дублювання власності каналу або інструмента Симптоми: @@ -345,34 +379,34 @@ OpenClaw сканує plugins у такому порядку (перше спі - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, +Це означає, що більше ніж один увімкнений plugin намагається володіти тим самим каналом, потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній channel plugin, встановлений поруч із bundled plugin, який тепер надає той самий channel id. Кроки налагодження: -- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin +- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin і його походження. -- Запустіть `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і - порівняйте `channels`, `channelConfigs`, `tools` і діагностику. +- Запустіть `openclaw plugins inspect --runtime --json` для кожного підозрюваного plugin і + порівняйте `channels`, `channelConfigs`, `tools` і diagnostics. - Запустіть `openclaw plugins registry --refresh` після встановлення або видалення plugin packages, щоб збережені metadata відображали поточне встановлення. -- Перезапустіть Gateway після змін встановлення, registry або конфігурації. +- Перезапустіть Gateway після змін install, registry або config. Варіанти виправлення: -- Якщо один Plugin навмисно замінює інший для того самого channel id, бажаний - Plugin має оголосити `channelConfigs..preferOver` з - нижчопріоритетним plugin id. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). +- Якщо один plugin навмисно замінює інший для того самого channel id, бажаний + plugin має оголосити `channelConfigs..preferOver` з id plugin нижчого пріоритету. + Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). - Якщо дублювання випадкове, вимкніть одну сторону через - `plugins.entries..enabled: false` або видаліть застаріле встановлення Plugin. + `plugins.entries..enabled: false` або видаліть застаріле встановлення plugin. - Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, - що належать Plugin, щоб runtime surface була однозначною. + що належать plugin, щоб runtime surface була однозначною. ## Слоти Plugin (ексклюзивні категорії) -Деякі категорії є ексклюзивними (активною може бути лише одна за раз): +Деякі категорії є ексклюзивними (активна лише одна за раз): ```json5 { @@ -385,9 +419,9 @@ OpenClaw сканує plugins у такому порядку (перше спі } ``` -| Слот | Що він контролює | За замовчуванням | +| Слот | Що він контролює | Значення за замовчуванням | | --------------- | --------------------- | ------------------- | -| `memory` | Plugin active memory | `memory-core` | +| `memory` | Plugin активної пам’яті | `memory-core` | | `contextEngine` | Активний context engine | `legacy` (вбудований) | ## Довідник CLI @@ -437,79 +471,79 @@ openclaw plugins enable openclaw plugins disable ``` -Bundled plugins постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад +Bundled plugins постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад bundled model providers, bundled speech providers і bundled browser plugin). Інші bundled plugins все ще потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений Plugin або hook pack на місці. Використовуйте -`openclaw plugins update ` для регулярних оновлень відстежуваних npm -plugins. Це не підтримується з `--link`, який повторно використовує шлях джерел замість +`--force` перезаписує наявний встановлений plugin або hook pack на місці. Використовуйте +`openclaw plugins update ` для звичайних оновлень відстежуваних npm +plugins. Це не підтримується з `--link`, який повторно використовує шлях вихідного коду замість копіювання поверх керованої цілі встановлення. -Коли `plugins.allow` уже задано, `openclaw plugins install` додає id -встановленого Plugin до цього allowlist перед його ввімкненням. Якщо той самий plugin id +Коли `plugins.allow` уже встановлено, `openclaw plugins install` додає +id встановленого plugin до цього allowlist перед його ввімкненням. Якщо той самий plugin id присутній у `plugins.deny`, install видаляє цей застарілий запис deny, щоб -явне встановлення можна було одразу завантажити після перезапуску. +явне встановлення можна було завантажити одразу після перезапуску. -OpenClaw зберігає persistent local plugin registry як cold read model для -інвентаризації Plugin, власності contributions і планування запуску. Потоки install, update, -uninstall, enable і disable оновлюють цей registry після зміни стану Plugin. +OpenClaw зберігає локальний реєстр plugin як модель холодного читання для +інвентаризації plugins, власності внесків і планування запуску. Потоки install, update, +uninstall, enable і disable оновлюють цей registry після зміни стану plugin. Той самий файл `plugins/installs.json` зберігає довговічні install metadata у -top-level `installRecords` і перебудовувані manifest metadata у `plugins`. Якщо +верхньорівневому `installRecords` і відновлювані manifest metadata у `plugins`. Якщо registry відсутній, застарілий або недійсний, `openclaw plugins registry ---refresh` перебудовує його manifest view з install records, config policy і -manifest/package metadata без завантаження runtime modules Plugin. -`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -npm package spec з dist-tag або точною версією розв’язує package name -назад до відстежуваного запису Plugin і записує новий spec для майбутніх оновлень. -Передавання package name без версії переводить exact pinned install назад на -лінію релізів за замовчуванням registry. Якщо встановлений npm plugin уже відповідає -розв’язаній версії та записаній ідентичності артефакта, OpenClaw пропускає оновлення -без завантаження, перевстановлення або перезапису конфігурації. +--refresh` перебудовує його manifest view із install records, config policy і +manifest/package metadata без завантаження runtime modules plugin. +`openclaw plugins update ` застосовується до відстежуваних install. Передавання +npm package spec з dist-tag або exact version розв’язує назву пакета +назад до відстежуваного запису plugin і записує новий spec для майбутніх updates. +Передавання назви пакета без версії повертає точне pinned install назад до +типової release line registry. Якщо встановлений npm plugin уже відповідає +розв’язаній версії та записаній artifact identity, OpenClaw пропускає update +без завантаження, перевстановлення або перезапису config. -`--pin` є лише для npm. Він не підтримується з `--marketplace`, тому що +`--pin` працює лише для npm. Він не підтримується з `--marketplace`, тому що marketplace installs зберігають metadata джерела marketplace замість npm spec. `--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних -спрацювань вбудованого dangerous-code scanner. Воно дозволяє встановлення Plugin -і оновлення Plugin продовжуватися попри вбудовані findings рівня `critical`, але все одно -не обходить блокування plugin `before_install` policy або блокування через scan-failure. -Install scans ігнорують типові тестові файли та директорії, як-от `tests/`, -`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати packaged test mocks; -оголошені runtime entrypoints Plugin усе одно скануються, навіть якщо вони використовують одну з +спрацьовувань вбудованого dangerous-code scanner. Воно дозволяє plugin installs +і plugin updates продовжуватися після вбудованих findings рівня `critical`, але все одно +не обходить блокування політики `before_install` plugin або блокування через scan failure. +Install scans ігнорують поширені тестові файли й каталоги, як-от `tests/`, +`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати упаковані test mocks; +оголошені runtime entrypoints plugin усе одно скануються, навіть якщо вони використовують одну з цих назв. -Цей CLI flag застосовується лише до потоків install/update Plugin. Встановлення skill -dependencies через Gateway використовують відповідне override запиту +Цей CLI flag застосовується лише до потоків install/update plugin. Встановлення залежностей Skills +на базі Gateway натомість використовують відповідний override запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком -завантаження/встановлення Skills з ClawHub. +завантаження/встановлення ClawHub skill. -Якщо Plugin, який ви опублікували на ClawHub, прихований або заблокований скануванням, відкрийте -dashboard ClawHub або запустіть `clawhub package rescan `, щоб попросити ClawHub перевірити +Якщо Plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте +панель ClawHub або запустіть `clawhub package rescan `, щоб попросити ClawHub перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному -комп’ютері; він не просить ClawHub повторно сканувати Plugin або робити заблокований реліз +комп’ютері; він не просить ClawHub повторно просканувати Plugin і не робить заблокований випуск публічним. -Сумісні бандли беруть участь у тому самому потоці list/inspect/enable/disable для Plugin. -Поточна підтримка runtime включає bundle skills, Claude command-skills, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і manifest-declared -`lspServers`, Cursor command-skills і сумісні директорії Codex hooks. +Сумісні пакети беруть участь у тому самому потоці перегляду списку/інспектування/увімкнення/вимкнення +Plugins. Поточна підтримка середовища виконання охоплює пакетні Skills, command-skills Claude, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті +`lspServers`, command-skills Cursor, а також сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також повідомляє виявлені можливості bundle, а також -підтримувані або непідтримувані записи серверів MCP і LSP для bundle-backed plugins. +`openclaw plugins inspect ` також повідомляє виявлені можливості пакета, а також +підтримувані або непідтримувані записи серверів MCP і LSP для Plugins на основі пакетів. -Джерелами маркетплейсу можуть бути відома Claude назва маркетплейсу з -`~/.claude/plugins/known_marketplaces.json`, локальний корінь маркетплейсу або -шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію -GitHub або git URL. Для віддалених маркетплейсів записи плагінів мають залишатися всередині -клонованого репозиторію маркетплейсу й використовувати лише відносні джерела шляхів. +Джерелами маркетплейсу можуть бути відома назва маркетплейсу Claude з +`~/.claude/plugins/known_marketplaces.json`, локальний корінь маркетплейсу або шлях +`marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub +або git URL. Для віддалених маркетплейсів записи Plugins мають залишатися всередині +клонованого репозиторію маркетплейсу й використовувати лише джерела з відносними шляхами. -Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins). +Докладні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins). ## Огляд API Plugin -Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші -плагіни можуть іще використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають +Нативні Plugins експортують об’єкт входу, який надає `register(api)`. Старіші +Plugins усе ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові Plugins мають використовувати `register`. ```typescript @@ -530,75 +564,75 @@ export default definePluginEntry({ }); ``` -OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації плагіна. -Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, -але вбудовані плагіни й нові зовнішні плагіни мають розглядати `register` як +OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації Plugin. +Завантажувач усе ще повертається до `activate(api)` для старіших Plugins, +але вбудовані Plugins і нові зовнішні Plugins мають розглядати `register` як публічний контракт. -`api.registrationMode` повідомляє плагіну, чому завантажується його вхід: +`api.registrationMode` повідомляє Plugin, чому завантажується його вхід: | Режим | Значення | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація під час виконання. Реєструє інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | -| `discovery` | Доступне лише для читання виявлення можливостей. Реєструє провайдерів і метадані; довірений код входу плагіна може завантажуватися, але активні побічні ефекти слід пропускати. | -| `setup-only` | Завантаження метаданих налаштування каналу через легковаговий вхід налаштування. | -| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід часу виконання. | +| `full` | Активація середовища виконання. Реєструє інструменти, хуки, сервіси, команди, маршрути та інші активні побічні ефекти. | +| `discovery` | Виявлення можливостей лише для читання. Реєструє провайдерів і метадані; довірений код входу Plugin може завантажуватися, але має пропускати активні побічні ефекти. | +| `setup-only` | Завантаження метаданих налаштування каналу через полегшений вхід налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | | `cli-metadata` | Лише збирання метаданих команд CLI. | -Входи плагінів, які відкривають сокети, бази даних, фонових працівників або довгоживучі -клієнти, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`. +Записи Plugins, які відкривають сокети, бази даних, фонові воркери або довготривалих +клієнтів, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`. Завантаження виявлення кешуються окремо від завантажень активації й не замінюють -поточний реєстр Gateway. Виявлення не активує, але й не є вільним від імпортів: -OpenClaw може виконати довірений вхід плагіна або модуль канального плагіна, щоб побудувати -знімок. Тримайте верхні рівні модулів легковаговими й без побічних ефектів, а -мережевих клієнтів, підпроцеси, слухачі, читання облікових даних і запуск служб -переносьте за шляхи повного виконання. +поточний реєстр Gateway. Виявлення не активує, але не є вільним від імпорту: +OpenClaw може виконувати довірений вхід Plugin або модуль Plugin каналу, щоб побудувати +знімок. Тримайте верхні рівні модулів легкими й без побічних ефектів, а мережеві +клієнти, підпроцеси, слухачі, читання облікових даних і запуск сервісів перемістіть +за шляхи повного середовища виконання. Поширені методи реєстрації: -| Метод | Що він реєструє | -| --------------------------------------- | --------------------------- | -| `registerProvider` | Провайдер моделі (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Перетворення тексту на мовлення / STT | -| `registerRealtimeTranscriptionProvider` | Потоковий STT | -| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер вебзавантаження / скрейпінгу | -| `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 передає нативні для Codex події інструментів назад у цю -поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, +Нативний сервер застосунку Codex передає нативні події інструментів Codex назад у цю +поверхню хуків. Plugins можуть блокувати нативні інструменти Codex через `before_tool_call`, спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex `PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. Точна межа підтримки середовища виконання Codex описана в -[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). +[контракті підтримки v1 середовища Codex](/uk/plugins/codex-harness#v1-support-contract). Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін -- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Створення Plugins](/uk/plugins/building-plugins) — створіть власний Plugin +- [Пакети Plugins](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor - [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагін -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Плагіни спільноти](/uk/plugins/community) — сторонні каталоги +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin +- [Внутрішня архітектура Plugins](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Спільнотні Plugins](/uk/plugins/community) — списки сторонніх Plugins