From 23b2a97c59a333a02ca8499bfbe659e9f3442828 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 02:12:12 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/qqbot.md | 139 ++-- docs/uk/channels/yuanbao.md | 126 ++-- docs/uk/cli/models.md | 153 ++--- docs/uk/help/testing.md | 809 ++++++++++++----------- docs/uk/plugins/compatibility.md | 159 +++-- docs/uk/plugins/manifest.md | 1063 ++++++++++++++++-------------- docs/uk/plugins/sdk-subpaths.md | 480 +++++++------- docs/uk/plugins/sdk-testing.md | 242 +++---- 8 files changed, 1665 insertions(+), 1506 deletions(-) diff --git a/docs/uk/channels/qqbot.md b/docs/uk/channels/qqbot.md index 2ae873af1..5b0fa6915 100644 --- a/docs/uk/channels/qqbot.md +++ b/docs/uk/channels/qqbot.md @@ -2,30 +2,30 @@ read_when: - Ви хочете підключити OpenClaw до QQ - Вам потрібно налаштувати облікові дані QQ Bot - - Ви хочете підтримку групових або приватних чатів QQ Bot + - Вам потрібна підтримка групового або приватного чату QQ Bot summary: Налаштування, конфігурація та використання QQ Bot title: QQ bot x-i18n: - generated_at: "2026-04-26T07:47:31Z" + generated_at: "2026-04-28T02:07:56Z" model: gpt-5.4 provider: openai - source_hash: bd899d9556ab418bbb3d7dc368e6f6e1eca96828cbcc87b4147ccad362f1918e + source_hash: aefece6b05bb16d5c4f588bf7af4fd710b5f98aab0dbed8221490c46bf3f379c source_path: channels/qqbot.md workflow: 15 --- -QQ Bot підключається до OpenClaw через офіційний API QQ Bot (шлюз WebSocket). Плагін підтримує приватні чати C2C, групові @повідомлення та повідомлення в каналах guild із мультимедіа (зображення, голос, відео, файли). +QQ Bot підключається до OpenClaw через офіційний API QQ Bot (WebSocket gateway). Плагін підтримує приватні чати C2C, групові @повідомлення та повідомлення каналів guild із підтримкою мультимедіа (зображення, голос, відео, файли). -Статус: вбудований плагін. Підтримуються прямі повідомлення, групові чати, канали guild і медіа. Реакції та треди не підтримуються. +Статус: вбудований плагін. Підтримуються прямі повідомлення, групові чати, канали guild і мультимедіа. Реакції та треди не підтримуються. ## Вбудований плагін -Поточні випуски OpenClaw містять QQ Bot у комплекті, тому звичайним пакетним збіркам не потрібен окремий крок `openclaw plugins install`. +Поточні випуски OpenClaw постачаються з QQ Bot, тому у звичайних пакетних збірках не потрібен окремий крок `openclaw plugins install`. ## Налаштування -1. Перейдіть на [QQ Open Platform](https://q.qq.com/) і відскануйте QR-код за допомогою QQ на телефоні, щоб зареєструватися / увійти. -2. Натисніть **Create Bot**, щоб створити нового QQ-бота. +1. Перейдіть на [QQ Open Platform](https://q.qq.com/) і відскануйте QR-код у QQ на телефоні, щоб зареєструватися / увійти. +2. Натисніть **Create Bot**, щоб створити нового QQ bot. 3. Знайдіть **AppID** і **AppSecret** на сторінці налаштувань бота та скопіюйте їх. > AppSecret не зберігається у відкритому вигляді — якщо ви залишите сторінку, не зберігши його, вам доведеться згенерувати новий. @@ -82,13 +82,13 @@ AppSecret із файла: Примітки: -- Резервне використання змінних середовища застосовується лише до облікового запису QQ Bot за замовчуванням. -- `openclaw channels add --channel qqbot --token-file ...` надає лише AppSecret; AppID уже має бути заданий у конфігурації або в `QQBOT_APP_ID`. -- `clientSecret` також приймає вхід SecretRef, а не лише рядок відкритого тексту. +- Підстановка зі змінних середовища застосовується лише до облікового запису QQ Bot за замовчуванням. +- `openclaw channels add --channel qqbot --token-file ...` передає лише AppSecret; AppID уже має бути заданий у конфігурації або в `QQBOT_APP_ID`. +- `clientSecret` також приймає вхід SecretRef, а не лише рядок у відкритому вигляді. ### Налаштування кількох облікових записів -Запустіть кілька QQ-ботів в одному екземплярі OpenClaw: +Запустіть кілька QQ bot в одному екземплярі OpenClaw: ```json5 { @@ -117,14 +117,56 @@ AppSecret із файла: openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" ``` +### Групові чати + +Підтримка групових чатів QQ Bot використовує OpenID груп QQ, а не відображувані імена. Додайте бота до групи, а потім згадайте його або налаштуйте групу на роботу без згадки. + +```json5 +{ + channels: { + qqbot: { + groupPolicy: "allowlist", + groupAllowFrom: ["member_openid"], + groups: { + "*": { + requireMention: true, + historyLimit: 50, + toolPolicy: "restricted", + }, + GROUP_OPENID: { + name: "Release room", + requireMention: false, + ignoreOtherMentions: true, + historyLimit: 20, + prompt: "Keep replies short and operational.", + }, + }, + }, + }, +} +``` + +`groups["*"]` задає значення за замовчуванням для кожної групи, а конкретний запис `groups.GROUP_OPENID` перевизначає ці значення для однієї групи. Налаштування групи включають: + +- `requireMention`: вимагати @згадку перед відповіддю бота. За замовчуванням: `true`. +- `ignoreOtherMentions`: відкидати повідомлення, які згадують когось іншого, але не бота. +- `historyLimit`: зберігати нещодавні групові повідомлення без згадки як контекст для наступного ходу зі згадкою. Установіть `0`, щоб вимкнути. +- `toolPolicy`: `full`, `restricted` або `none` для інструментів рівня групи. +- `name`: зрозуміла мітка, що використовується в журналах і контексті групи. +- `prompt`: промпт поведінки для групи, який додається до контексту агента. + +Режими активації — `mention` і `always`. `requireMention: true` відповідає `mention`; `requireMention: false` відповідає `always`. Якщо є перевизначення активації на рівні сесії, воно має пріоритет над конфігурацією. + +Вхідна черга є окремою для кожного peer. Для peer груп застосовується більший ліміт черги, повідомлення людей зберігають пріоритет над повідомленнями, створеними ботом, коли черга переповнена, а серії звичайних групових повідомлень об’єднуються в один атрибутований хід. Slash commands, як і раніше, виконуються по одному. + ### Голос (STT / TTS) -Підтримка STT і TTS має дворівневу конфігурацію з резервним пріоритетом: +Підтримка STT і TTS має дворівневу конфігурацію з пріоритетною підстановкою: -| Параметр | Специфічно для плагіна | Резервне значення фреймворку | -| ------- | -------------------------------------------------------- | ----------------------------- | -| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | -| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | +| Налаштування | Специфічно для плагіна | Резервне значення фреймворку | +| ------------ | ------------------------------------------------------ | ---------------------------- | +| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | +| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | ```json5 { @@ -154,9 +196,9 @@ openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-o ``` Установіть `enabled: false` для будь-якого з них, щоб вимкнути. -Перевизначення TTS на рівні облікового запису використовують ту саму структуру, що й `messages.tts`, і виконують глибоке злиття поверх TTS-конфігурації каналу/глобальної конфігурації. +Перевизначення TTS на рівні облікового запису використовують ту саму структуру, що й `messages.tts`, і виконують глибоке злиття поверх конфігурації TTS каналу/глобальної конфігурації. -Вхідні голосові вкладення QQ надаються агентам як метадані аудіомедіа, при цьому сирі голосові файли не потрапляють до загальних `MediaPaths`. Звичайні текстові відповіді `[[audio_as_voice]]` синтезують TTS і надсилають нативне голосове повідомлення QQ, якщо TTS налаштовано. +Вхідні голосові вкладення QQ надаються агентам як метадані аудіо, при цьому сирі голосові файли не потрапляють до загального `MediaPaths`. Текстові відповіді `[[audio_as_voice]]` синтезують TTS і надсилають нативне голосове повідомлення QQ, коли TTS налаштовано. Поведінку вивантаження/транскодування вихідного аудіо також можна налаштувати через `channels.qqbot.audioFormatPolicy`: @@ -166,59 +208,60 @@ openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-o ## Цільові формати -| Формат | Опис | -| -------------------------- | -------------------- | -| `qqbot:c2c:OPENID` | Приватний чат (C2C) | -| `qqbot:group:GROUP_OPENID` | Груповий чат | -| `qqbot:channel:CHANNEL_ID` | Канал guild | +| Формат | Опис | +| -------------------------- | ------------------ | +| `qqbot:c2c:OPENID` | Приватний чат (C2C) | +| `qqbot:group:GROUP_OPENID` | Груповий чат | +| `qqbot:channel:CHANNEL_ID` | Канал guild | > Кожен бот має власний набір OpenID користувачів. OpenID, отриманий ботом A, **не можна** використовувати для надсилання повідомлень через бота B. -## Slash-команди +## Slash commands -Вбудовані команди, які перехоплюються до черги AI: +Вбудовані команди, які перехоплюються до AI-черги: -| Команда | Опис | -| -------------- | ---------------------------------------------------------------------------------------------------------------- | -| `/bot-ping` | Перевірка затримки | -| `/bot-version` | Показати версію фреймворку OpenClaw | -| `/bot-help` | Перелічити всі команди | -| `/bot-upgrade` | Показати посилання на посібник з оновлення QQBot | -| `/bot-logs` | Експортувати нещодавні журнали Gateway у вигляді файла | +| Команда | Опис | +| -------------- | ----------------------------------------------------------------------------------------------------------------- | +| `/bot-ping` | Перевірка затримки | +| `/bot-version` | Показати версію фреймворку OpenClaw | +| `/bot-help` | Показати список усіх команд | +| `/bot-upgrade` | Показати посилання на інструкцію з оновлення QQBot | +| `/bot-logs` | Експортувати нещодавні журнали Gateway як файл | | `/bot-approve` | Схвалити очікувану дію QQ Bot (наприклад, підтвердження вивантаження C2C або групи) через нативний потік. | -Додайте `?` до будь-якої команди, щоб отримати довідку щодо використання (наприклад, `/bot-upgrade ?`). +Додайте `?` до будь-якої команди, щоб отримати довідку з використання (наприклад, `/bot-upgrade ?`). ## Архітектура рушія QQ Bot постачається як самодостатній рушій усередині плагіна: -- Кожен обліковий запис володіє ізольованим стеком ресурсів (WebSocket-з’єднання, API-клієнт, кеш токенів, кореневий каталог сховища медіа), прив’язаним до `appId`. Облікові записи ніколи не ділять між собою вхідний або вихідний стан. -- Логер для кількох облікових записів позначає рядки журналу власником облікового запису, щоб діагностика залишалася роздільною, коли ви запускаєте кількох ботів під одним Gateway. -- Шляхи вхідного, вихідного та bridge-шлюзу використовують єдиний корінь медіаданих у `~/.openclaw/media`, тож вивантаження, завантаження та кеші транскодування потрапляють в один захищений каталог замість дерева для кожної підсистеми окремо. -- Облікові дані можна резервно копіювати та відновлювати як частину стандартних знімків облікових даних OpenClaw; після відновлення рушій повторно приєднує стек ресурсів кожного облікового запису без потреби в новому паруванні через QR-код. +- Кожен обліковий запис має ізольований стек ресурсів (WebSocket-з’єднання, API-клієнт, кеш токенів, кореневий каталог медіасховища), прив’язаний до `appId`. Облікові записи ніколи не ділять між собою стан вхідних/вихідних даних. +- Логер для кількох облікових записів додає до рядків журналу мітку відповідного облікового запису, щоб діагностику можна було розділяти при запуску кількох ботів в одному gateway. +- Шляхи вхідних даних, вихідних даних і bridge gateway використовують єдиний кореневий каталог медіаданих у `~/.openclaw/media`, тому вивантаження, завантаження та кеші транскодування потрапляють до одного захищеного каталогу, а не до окремого дерева для кожної підсистеми. +- Доставка мультимедіа проходить через єдиний шлях `sendMedia` для цілей C2C і груп. Локальні файли та буфери, що перевищують поріг великого файла, використовують endpoints QQ для частинного вивантаження, тоді як менші навантаження використовують одноразовий API мультимедіа. +- Облікові дані можна резервно копіювати та відновлювати в межах стандартних знімків облікових даних OpenClaw; після відновлення рушій знову приєднує стек ресурсів кожного облікового запису без потреби в новому сполученні через QR-код. ## Онбординг через QR-код -Як альтернатива ручному вставлянню `AppID:AppSecret`, рушій підтримує потік онбордингу через QR-код для прив’язки QQ Bot до OpenClaw: +Як альтернатива ручному вставленню `AppID:AppSecret`, рушій підтримує потік онбордингу через QR-код для прив’язки QQ Bot до OpenClaw: -1. Запустіть шлях налаштування QQ Bot (наприклад, `openclaw channels add --channel qqbot`) і виберіть потік із QR-кодом, коли буде запропоновано. -2. Відскануйте згенерований QR-код за допомогою телефонного застосунку, прив’язаного до цільового QQ Bot. -3. Схваліть сполучення на телефоні. OpenClaw збереже повернені облікові дані в `credentials/` у правильній області облікового запису. +1. Запустіть шлях налаштування QQ Bot (наприклад, `openclaw channels add --channel qqbot`) і виберіть потік QR-коду, коли з’явиться запит. +2. Відскануйте згенерований QR-код у застосунку телефона, пов’язаного з цільовим QQ Bot. +3. Підтвердьте сполучення на телефоні. OpenClaw збереже отримані облікові дані в `credentials/` у правильній області облікового запису. -Запити на схвалення, згенеровані самим ботом (наприклад, потоки «дозволити цю дію?», які надає API QQ Bot), відображаються як нативні запити OpenClaw, які можна прийняти за допомогою `/bot-approve`, а не відповідати через сирий клієнт QQ. +Запити на схвалення, згенеровані самим ботом (наприклад, потоки "allow this action?", які надає API QQ Bot), відображаються як нативні запити OpenClaw, які можна прийняти через `/bot-approve`, а не відповідати через сирий клієнт QQ. ## Усунення несправностей -- **Бот відповідає "gone to Mars":** облікові дані не налаштовані або Gateway не запущено. +- **Бот відповідає "gone to Mars":** облікові дані не налаштовано або Gateway не запущено. - **Немає вхідних повідомлень:** перевірте, що `appId` і `clientSecret` правильні, і що бот увімкнений на QQ Open Platform. -- **Повторні відповіді самому собі:** OpenClaw записує індекси вихідних QQ ref як створені ботом і ігнорує вхідні події, у яких поточний `msgIdx` збігається з тим самим обліковим записом бота. Це запобігає циклам echo платформи, водночас дозволяючи користувачам цитувати або відповідати на попередні повідомлення бота. -- **Після налаштування з `--token-file` усе ще показується неналаштований стан:** `--token-file` задає лише AppSecret. Вам усе ще потрібен `appId` у конфігурації або `QQBOT_APP_ID`. +- **Повторні відповіді самому собі:** OpenClaw записує індекси вихідних QQ ref як створені ботом і ігнорує вхідні події, у яких поточний `msgIdx` збігається з тим самим обліковим записом бота. Це запобігає циклам echo на платформі й водночас дозволяє користувачам цитувати або відповідати на попередні повідомлення бота. +- **Налаштування з `--token-file` усе ще показує, що не налаштовано:** `--token-file` задає лише AppSecret. Вам усе ще потрібен `appId` у конфігурації або `QQBOT_APP_ID`. - **Проактивні повідомлення не надходять:** QQ може перехоплювати повідомлення, ініційовані ботом, якщо користувач не взаємодіяв нещодавно. -- **Голос не транскрибується:** переконайтеся, що STT налаштовано і що провайдер доступний. +- **Голос не транскрибується:** переконайтеся, що STT налаштовано і провайдер доступний. ## Пов’язане - [Сполучення](/uk/channels/pairing) - [Групи](/uk/channels/groups) -- [Усунення несправностей каналів](/uk/channels/troubleshooting) +- [Усунення несправностей каналу](/uk/channels/troubleshooting) diff --git a/docs/uk/channels/yuanbao.md b/docs/uk/channels/yuanbao.md index 757d67d01..97f6b46be 100644 --- a/docs/uk/channels/yuanbao.md +++ b/docs/uk/channels/yuanbao.md @@ -1,36 +1,38 @@ --- read_when: - - Ви хочете підключити бота YuanBao - - Ви налаштовуєте канал YuanBao -summary: Огляд, функції та конфігурація бота YuanBao -title: YuanBao + - Ви хочете підключити бота Yuanbao + - Ви налаштовуєте канал Yuanbao +summary: Огляд бота Yuanbao, функції та конфігурація +title: Yuanbao x-i18n: - generated_at: "2026-04-27T15:07:59Z" + generated_at: "2026-04-28T02:07:53Z" model: gpt-5.4 provider: openai - source_hash: 6a9177cba0fb64b9d47762450ff9ec7b0ae497ed0027f98f35dbd6b1bc252110 + source_hash: d82b6d275ae8aa4cc5e62321772c5ba2b5044c6058be0d2e5215cdb1488118e9 source_path: channels/yuanbao.md workflow: 15 --- -# YuanBao +# Yuanbao -YuanBao — це платформа AI-асистента від Tencent, яка підтримує інтеграцію ботів через миттєві повідомлення. Боти можуть взаємодіяти з користувачами через особисті повідомлення та групові чати. +Tencent Yuanbao — це платформа AI-асистента від Tencent. Плагін каналу OpenClaw +підключає ботів Yuanbao до OpenClaw через WebSocket, щоб вони могли взаємодіяти з користувачами +через особисті повідомлення та групові чати. -**Статус:** готово до використання в продакшені для особистих повідомлень ботів і групових чатів. WebSocket — єдиний підтримуваний режим підключення. +**Статус:** готово до використання у production для особистих повідомлень ботів і групових чатів. WebSocket — єдиний підтримуваний режим підключення. --- ## Швидкий старт -> **Потрібен OpenClaw 2026.4.10 або новіший.** Виконайте `openclaw --version`, щоб перевірити. Оновіть за допомогою `openclaw update`. +> **Потрібен OpenClaw 2026.4.10 або новіший.** Щоб перевірити версію, виконайте `openclaw --version`. Оновіть за допомогою `openclaw update`. - + ```bash openclaw channels add --channel yuanbao --token "appKey:appSecret" ``` - Значення `--token` використовує формат `appKey:appSecret`, розділений двокрапкою. Ви можете отримати ці дані з YuanBao APP, створивши робота в налаштуваннях вашого застосунку. + Значення `--token` використовує формат `appKey:appSecret`, розділений двокрапкою. Ви можете отримати ці значення з застосунку Yuanbao, створивши робота в налаштуваннях вашого застосунку. @@ -99,7 +101,7 @@ openclaw pairing approve yuanbao } ``` -### Обмежити особисті повідомлення для конкретних користувачів +### Обмеження особистих повідомлень для конкретних користувачів ```json5 { @@ -116,7 +118,7 @@ openclaw pairing approve yuanbao } ``` -### Вимкнути вимогу @згадки в групах +### Вимкнення вимоги @згадки в групах ```json5 { @@ -128,29 +130,29 @@ openclaw pairing approve yuanbao } ``` -### Оптимізувати надсилання вихідних повідомлень +### Оптимізація доставки вихідних повідомлень ```json5 { channels: { yuanbao: { - // Надсилайте кожен фрагмент одразу без буферизації + // Надсилати кожен фрагмент одразу без буферизації outboundQueueStrategy: "immediate", }, }, } ``` -### Налаштувати стратегію merge-text +### Налаштування стратегії merge-text ```json5 { channels: { yuanbao: { outboundQueueStrategy: "merge-text", - minChars: 2800, // буферизувати до цієї кількості символів - maxChars: 3000, // примусово розділити вище цього ліміту - idleMs: 5000, // автоматичне скидання після тайм-ауту неактивності (мс) + minChars: 2800, // буферизувати, доки не буде стільки символів + maxChars: 3000, // примусовий поділ понад цей ліміт + idleMs: 5000, // автоматичне скидання після простою (мс) }, }, } @@ -160,41 +162,41 @@ openclaw pairing approve yuanbao ## Поширені команди -| Команда | Опис | -| ---------- | ------------------------------ | -| `/help` | Показати доступні команди | -| `/status` | Показати статус бота | -| `/new` | Почати нову сесію | -| `/stop` | Зупинити поточний запуск | -| `/restart` | Перезапустити OpenClaw | +| Команда | Опис | +| ---------- | ----------------------------- | +| `/help` | Показати доступні команди | +| `/status` | Показати статус бота | +| `/new` | Почати нову сесію | +| `/stop` | Зупинити поточний запуск | +| `/restart` | Перезапустити OpenClaw | | `/compact` | Виконати Compaction контексту сесії | -> YuanBao підтримує вбудовані меню slash-команд. Команди автоматично синхронізуються з платформою під час запуску Gateway. +> Yuanbao підтримує вбудовані меню slash-команд. Команди автоматично синхронізуються з платформою під час запуску Gateway. --- -## Усунення несправностей +## Усунення проблем ### Бот не відповідає в групових чатах 1. Переконайтеся, що бота додано до групи -2. Переконайтеся, що ви згадуєте бота через @ (це потрібно типово) +2. Переконайтеся, що ви згадуєте бота через @ (типово це обов’язково) 3. Перевірте журнали: `openclaw logs --follow` ### Бот не отримує повідомлення -1. Переконайтеся, що бота створено та схвалено в YuanBao APP -2. Переконайтеся, що `appKey` і `appSecret` налаштовано правильно +1. Переконайтеся, що бот створений і підтверджений у застосунку Yuanbao +2. Переконайтеся, що `appKey` і `appSecret` налаштовані правильно 3. Переконайтеся, що Gateway запущено: `openclaw gateway status` 4. Перевірте журнали: `openclaw logs --follow` ### Бот надсилає порожні або резервні відповіді -1. Перевірте, чи модель AI повертає коректний вміст +1. Перевірте, чи AI-модель повертає коректний вміст 2. Типова резервна відповідь: "暂时无法解答，你可以换个问题问问我哦" 3. Налаштуйте її через `channels.yuanbao.fallbackReply` -### Витік App Secret +### App Secret скомпрометовано 1. Скиньте App Secret у YuanBao APP 2. Оновіть значення у своїй конфігурації @@ -215,12 +217,12 @@ openclaw pairing approve yuanbao main: { appKey: "key_xxx", appSecret: "secret_xxx", - name: "Основний бот", + name: "Primary bot", }, backup: { appKey: "key_yyy", appSecret: "secret_yyy", - name: "Резервний бот", + name: "Backup bot", enabled: false, }, }, @@ -229,7 +231,7 @@ openclaw pairing approve yuanbao } ``` -`defaultAccount` керує тим, який обліковий запис використовується, коли вихідні API не вказують `accountId`. +`defaultAccount` визначає, який обліковий запис використовується, коли вихідні API не вказують `accountId`. ### Ліміти повідомлень @@ -239,7 +241,7 @@ openclaw pairing approve yuanbao ### Потокове передавання -YuanBao підтримує потокове виведення на рівні блоків. Коли його ввімкнено, бот надсилає текст фрагментами в процесі генерації. +Yuanbao підтримує потокове виведення на рівні блоків. Якщо ввімкнено, бот надсилає текст частинами в міру генерації. ```json5 { @@ -255,7 +257,7 @@ YuanBao підтримує потокове виведення на рівні ### Контекст історії групового чату -Керуйте тим, скільки історичних повідомлень включається в контекст AI для групових чатів: +Керуйте тим, скільки історичних повідомлень включається в AI-контекст для групових чатів: ```json5 { @@ -284,12 +286,12 @@ YuanBao підтримує потокове виведення на рівні | Значення | Поведінка | | --------- | -------------------------------------------------------- | | `"off"` | Без цитованої відповіді | -| `"first"` | Цитувати лише першу відповідь на одне вхідне повідомлення (типово) | +| `"first"` | Цитувати лише першу відповідь на кожне вхідне повідомлення (типово) | | `"all"` | Цитувати кожну відповідь | ### Вставка підказки для Markdown -Типово бот додає інструкції в системний промпт, щоб запобігти тому, що модель AI обгортає всю відповідь у markdown-блоки коду. +Типово бот додає інструкції в system prompt, щоб AI-модель не обгортала всю відповідь у markdown-блоки коду. ```json5 { @@ -315,9 +317,9 @@ YuanBao підтримує потокове виведення на рівні } ``` -### Маршрутизація з кількома агентами +### Маршрутизація між агентами -Використовуйте `bindings`, щоб маршрутизувати особисті повідомлення або групи YuanBao до різних агентів. +Використовуйте `bindings`, щоб маршрутизувати особисті повідомлення або групи Yuanbao до різних агентів. ```json5 { @@ -363,26 +365,26 @@ YuanBao підтримує потокове виведення на рівні | ----------------------------------------- | ------------------------------------------------- | -------------------------------------- | | `channels.yuanbao.enabled` | Увімкнути/вимкнути канал | `true` | | `channels.yuanbao.defaultAccount` | Типовий обліковий запис для вихідної маршрутизації | `default` | -| `channels.yuanbao.accounts..appKey` | App Key (використовується для підписування та створення квитків) | — | -| `channels.yuanbao.accounts..appSecret` | App Secret (використовується для підписування) | — | -| `channels.yuanbao.accounts..token` | Попередньо підписаний токен (пропускає автоматичне підписування квитків) | — | -| `channels.yuanbao.accounts..name` | Відображуване ім’я облікового запису | — | +| `channels.yuanbao.accounts..appKey` | App Key (використовується для підпису та генерації квитків) | — | +| `channels.yuanbao.accounts..appSecret` | App Secret (використовується для підпису) | — | +| `channels.yuanbao.accounts..token` | Попередньо підписаний токен (пропускає автоматичний підпис квитків) | — | +| `channels.yuanbao.accounts..name` | Відображувана назва облікового запису | — | | `channels.yuanbao.accounts..enabled` | Увімкнути/вимкнути конкретний обліковий запис | `true` | | `channels.yuanbao.dm.policy` | Політика особистих повідомлень | `open` | -| `channels.yuanbao.dm.allowFrom` | Список дозволених для особистих повідомлень (список ID користувачів) | — | +| `channels.yuanbao.dm.allowFrom` | Allowlist особистих повідомлень (список ID користувачів) | — | | `channels.yuanbao.requireMention` | Вимагати @згадку в групах | `true` | | `channels.yuanbao.overflowPolicy` | Обробка довгих повідомлень (`split` або `stop`) | `split` | -| `channels.yuanbao.replyToMode` | Стратегія reply-to у групах (`off`, `first`, `all`) | `first` | -| `channels.yuanbao.outboundQueueStrategy` | Вихідна стратегія (`merge-text` або `immediate`) | `merge-text` | -| `channels.yuanbao.minChars` | Merge-text: мінімум символів для запуску надсилання | `2800` | -| `channels.yuanbao.maxChars` | Merge-text: максимум символів у повідомленні | `3000` | -| `channels.yuanbao.idleMs` | Merge-text: тайм-аут неактивності перед автоскиданням (мс) | `5000` | +| `channels.yuanbao.replyToMode` | Стратегія group reply-to (`off`, `first`, `all`) | `first` | +| `channels.yuanbao.outboundQueueStrategy` | Вихідна стратегія (`merge-text` або `immediate`) | `merge-text` | +| `channels.yuanbao.minChars` | Merge-text: мінімум символів для запуску надсилання | `2800` | +| `channels.yuanbao.maxChars` | Merge-text: максимум символів на повідомлення | `3000` | +| `channels.yuanbao.idleMs` | Merge-text: тайм-аут простою перед автоскиданням (мс) | `5000` | | `channels.yuanbao.mediaMaxMb` | Ліміт розміру медіа (МБ) | `20` | -| `channels.yuanbao.historyLimit` | Кількість записів контексту історії групового чату | `100` | +| `channels.yuanbao.historyLimit` | Кількість записів історії в контексті групового чату | `100` | | `channels.yuanbao.disableBlockStreaming` | Вимкнути потокове виведення на рівні блоків | `false` | | `channels.yuanbao.fallbackReply` | Резервна відповідь, коли AI не повертає вміст | `暂时无法解答，你可以换个问题问问我哦` | | `channels.yuanbao.markdownHintEnabled` | Додавати інструкції проти обгортання в Markdown | `true` | -| `channels.yuanbao.debugBotIds` | Білий список ID ботів для налагодження (несанітизовані журнали) | `[]` | +| `channels.yuanbao.debugBotIds` | Debug whitelist ID ботів (несанітизовані журнали) | `[]` | --- @@ -393,9 +395,9 @@ YuanBao підтримує потокове виведення на рівні - ✅ Текст - ✅ Зображення - ✅ Файли -- ✅ Аудіо / голосові повідомлення +- ✅ Аудіо / голос - ✅ Відео -- ✅ Стікери / користувацькі emoji +- ✅ Стікери / користувацькі емодзі - ✅ Користувацькі елементи (картки посилань тощо) ### Надсилання @@ -407,17 +409,17 @@ YuanBao підтримує потокове виведення на рівні - ✅ Відео - ✅ Стікери -### Треди та відповіді +### Гілки та відповіді - ✅ Цитовані відповіді (налаштовується через `replyToMode`) -- ❌ Відповіді в тредах (не підтримується платформою) +- ❌ Відповіді в гілках (платформа не підтримує) --- ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Прив’язка](/uk/channels/pairing) — автентифікація особистих повідомлень і процес прив’язки -- [Групи](/uk/channels/groups) — поведінка групових чатів і керування через згадування +- [Прив’язка](/uk/channels/pairing) — автентифікація особистих повідомлень і потік прив’язки +- [Групи](/uk/channels/groups) — поведінка групових чатів і керування згадками - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту +- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту diff --git a/docs/uk/cli/models.md b/docs/uk/cli/models.md index a1c6ffe86..8ba054b09 100644 --- a/docs/uk/cli/models.md +++ b/docs/uk/cli/models.md @@ -1,27 +1,27 @@ --- read_when: - - Ви хочете змінити моделі за замовчуванням або переглянути стан автентифікації постачальника - - Ви хочете просканувати доступні моделі/постачальників і налагодити профілі автентифікації + - Ви хочете змінити моделі за замовчуванням або переглянути стан автентифікації провайдера + - Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація) title: Моделі x-i18n: - generated_at: "2026-04-27T20:08:44Z" + generated_at: "2026-04-28T02:07:56Z" model: gpt-5.4 provider: openai - source_hash: 1ff1d5d6b7e2d72ad0ff7480313ca67f7a49ec77ab198b688e7abf2b9de42757 + source_hash: 1bcbdaea238068441c0c8ff50c662d6b3e0f6c12dcf606bc1a3b52c1d71601ba source_path: cli/models.md workflow: 15 --- # `openclaw models` -Виявлення моделей, сканування та налаштування (модель за замовчуванням, резервні варіанти, профілі автентифікації). +Пошук моделей, сканування та налаштування (модель за замовчуванням, резервні варіанти, профілі автентифікації). -Пов’язано: +Пов’язане: -- Постачальники + моделі: [Моделі](/uk/providers/models) -- Концепції вибору моделей + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models) -- Налаштування автентифікації постачальника: [Початок роботи](/uk/start/getting-started) +- Провайдери + моделі: [Моделі](/uk/providers/models) +- Концепції вибору моделей + slash-команда `/models`: [Концепція моделей](/uk/concepts/models) +- Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started) ## Поширені команди @@ -32,18 +32,18 @@ openclaw models set openclaw models scan ``` -`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації. -Коли доступні знімки використання постачальника, розділ стану OAuth/API-ключа включає -вікна використання постачальника та знімки квот. -Поточні постачальники з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI -Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків, специфічних для постачальника, -коли вони доступні; інакше OpenClaw використовує резервний варіант і підбирає облікові дані -OAuth/API-ключа з профілів автентифікації, env або config. -У виводі `--json` `auth.providers` — це огляд постачальників з урахуванням env/config/store, +`openclaw models status` показує визначені значення за замовчуванням/резервні варіанти разом з оглядом автентифікації. +Коли доступні знімки використання провайдера, розділ стану OAuth/API-ключів містить +вікна використання провайдера та знімки квот. +Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI +Codex, MiniMax, Xiaomi та z.ai. Дані автентифікації для використання надходять із +специфічних для провайдера хуків, коли вони доступні; інакше OpenClaw використовує резервний варіант, зіставляючи облікові дані OAuth/API-ключів +із профілів автентифікації, змінних середовища або конфігурації. +У виводі `--json` `auth.providers` — це огляд провайдерів з урахуванням env/config/store, тоді як `auth.oauth` — це лише стан профілів у сховищі автентифікації. -Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю постачальника. -Перевірки — це реальні запити (можуть витрачати токени та спричиняти обмеження частоти). -Використовуйте `--agent `, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано, +Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера. +Перевірки — це реальні запити (можуть витрачати токени й спричиняти обмеження швидкості). +Використовуйте `--agent `, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо його не вказано, команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше — налаштованого агента за замовчуванням. Рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`. @@ -51,48 +51,53 @@ OAuth/API-ключа з профілів автентифікації, env аб Примітки: - `models set ` приймає `provider/model` або псевдонім. -- `models list` — лише для читання: команда читає config, профілі автентифікації, наявний стан каталогу - та рядки каталогу, що належать постачальнику, але не переписує +- `models list` є лише для читання: вона читає конфігурацію, профілі автентифікації, наявний + стан каталогу та рядки каталогу, що належать провайдерам, але не переписує `models.json`. -- `models list --all --provider ` може включати статичні рядки каталогу, що належать постачальнику, - із маніфестів Plugin або вбудованих метаданих каталогу постачальника, навіть якщо ви - ще не пройшли автентифікацію в цього постачальника. Такі рядки все одно відображаються як +- `models list --all --provider ` може включати статичні рядки каталогу, що належать провайдеру, + з маніфестів Plugin або вбудованих метаданих каталогу провайдера, навіть якщо ви + ще не автентифікувалися у цього провайдера. Такі рядки все одно показуються як недоступні, доки не буде налаштовано відповідну автентифікацію. -- `models list` зберігає нативні метадані моделі та ефективні обмеження runtime окремо. У табличному - виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне обмеження runtime - відрізняється від нативного вікна контексту; рядки JSON включають `contextTokens`, - коли постачальник надає це обмеження. -- `models list --provider ` фільтрує за id постачальника, наприклад `moonshot` або - `openai-codex`. Він не приймає мітки відображення з інтерактивних засобів вибору постачальника, +- Широкий `models list --all` об’єднує рядки каталогу маніфестів поверх рядків реєстру + без завантаження runtime-хуків доповнення провайдера. Швидкі шляхи маніфестів із фільтрацією за провайдером + використовують лише провайдерів, позначених як `static`; провайдери, позначені як `refreshable`, + залишаються прив’язаними до реєстру/кешу та додають рядки маніфесту як доповнення, тоді як + провайдери, позначені як `runtime`, залишаються на пошуку через реєстр/runtime. +- `models list` зберігає власні метадані моделі та runtime-обмеження окремо. У табличному + виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне runtime-обмеження + відрізняється від власного контекстного вікна; рядки JSON включають `contextTokens`, + коли провайдер надає таке обмеження. +- `models list --provider ` фільтрує за ідентифікатором провайдера, наприклад `moonshot` або + `openai-codex`. Він не приймає відображувані мітки з інтерактивних засобів вибору провайдера, наприклад `Moonshot AI`. -- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс постачальника (приклад: `openrouter/moonshotai/kimi-k2`). -- Якщо ви не вказали постачальника, OpenClaw спочатку визначає введення як псевдонім, потім — - як унікальний збіг exact model id серед налаштованих постачальників, і лише після цього - використовує резервний варіант із налаштованим постачальником за замовчуванням із попередженням про застарілість. - Якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw - використовує резервний варіант із першою налаштованою парою постачальник/модель замість того, щоб показувати - застаріле значення за замовчуванням від видаленого постачальника. -- `models status` може показувати `marker()` у виводі автентифікації для незахищених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. +- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). +- Якщо ви не вказали провайдера, OpenClaw спочатку розпізнає введення як псевдонім, потім — + як унікальний збіг точного ID моделі серед налаштованих провайдерів, і лише після цього + використовує резервний варіант у вигляді налаштованого провайдера за замовчуванням із попередженням про застарівання. + Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw + використовує резервний варіант — першу налаштовану пару провайдер/модель — замість того, щоб показувати + застаріле значення за замовчуванням для видаленого провайдера. +- `models status` може показувати `marker()` у виводі автентифікації для незасекречених плейсхолдерів (наприклад, `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. ### Сканування моделей `models scan` читає публічний каталог OpenRouter `:free` і ранжує кандидатів для -використання як резервних варіантів. Сам каталог є публічним, тому сканування лише метаданих не потребує -ключа OpenRouter. +використання як резервних варіантів. Сам каталог є публічним, тому сканування лише метаданих +не потребує ключа OpenRouter. За замовчуванням OpenClaw намагається перевірити підтримку інструментів і зображень за допомогою живих викликів моделі. -Якщо ключ OpenRouter не налаштовано, команда використовує резервний варіант із виводом лише метаданих -і пояснює, що моделі `:free` усе одно потребують `OPENROUTER_API_KEY` для -перевірок і висновку. +Якщо ключ OpenRouter не налаштовано, команда використовує резервний варіант у вигляді виводу лише метаданих +і пояснює, що моделі `:free` все одно потребують `OPENROUTER_API_KEY` для +перевірок і inference. Параметри: -- `--no-probe` (лише метадані; без пошуку config/секретів) +- `--no-probe` (лише метадані; без пошуку конфігурації/секретів) - `--min-params ` - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout ` (тайм-аут запиту каталогу та кожної перевірки) +- `--timeout ` (тайм-аут запиту каталогу та тайм-аут кожної перевірки) - `--concurrency ` - `--yes` - `--no-input` @@ -100,8 +105,8 @@ OAuth/API-ключа з профілів автентифікації, env аб - `--set-image` - `--json` -`--set-default` і `--set-image` потребують живих перевірок; результати сканування лише метаданих -є інформаційними та не застосовуються до config. +`--set-default` і `--set-image` потребують живих перевірок; результати сканування +лише за метаданими мають інформаційний характер і не застосовуються до конфігурації. ### Стан моделей @@ -109,20 +114,20 @@ OAuth/API-ключа з профілів автентифікації, env аб - `--json` - `--plain` -- `--check` (код виходу 1=прострочено/відсутнє, 2=строк дії спливає) +- `--check` (код виходу 1=прострочено/відсутнє, 2=скоро спливе) - `--probe` (жива перевірка налаштованих профілів автентифікації) -- `--probe-provider ` (перевірити одного постачальника) -- `--probe-profile ` (повторювані або розділені комами id профілів) +- `--probe-provider ` (перевірити один провайдер) +- `--probe-profile ` (повторювані або розділені комами ідентифікатори профілів) - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` -- `--agent ` (id налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) +- `--agent ` (ідентифікатор налаштованого агента; має пріоритет над `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) -`--json` зберігає stdout виключно для корисного навантаження JSON. Діагностика профілів автентифікації, постачальників -і запуску спрямовується в stderr, щоб скрипти могли напряму передавати stdout +`--json` зберігає stdout лише для JSON-корисного навантаження. Діагностика профілів автентифікації, провайдерів +і запуску спрямовується до stderr, щоб скрипти могли напряму передавати stdout в інструменти на кшталт `jq`. -Категорії стану перевірок: +Категорії стану перевірки: - `ok` - `auth` @@ -133,15 +138,15 @@ OAuth/API-ключа з профілів автентифікації, env аб - `unknown` - `no_model` -Варіанти деталей/кодів причин перевірок, на які слід очікувати: +Варіанти detail/reason-code перевірки, які варто очікувати: - `excluded_by_auth_order`: збережений профіль існує, але явний `auth.order.` його пропустив, тому перевірка повідомляє про виключення замість - спроби використати його. + спроби його використати. - `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`: - профіль присутній, але не придатний/не може бути визначений. -- `no_model`: автентифікація постачальника існує, але OpenClaw не зміг визначити - кандидата моделі для перевірки для цього постачальника. + профіль присутній, але не є придатним/не може бути розв’язаний. +- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити + кандидата моделі цього провайдера, придатного для перевірки. ## Псевдоніми + резервні варіанти @@ -159,12 +164,12 @@ openclaw models auth setup-token --provider openclaw models auth paste-token ``` -`models auth add` — це інтерактивний помічник автентифікації. Він може запустити потік автентифікації постачальника -(OAuth/API key) або провести вас через ручне вставлення токена, залежно від -вибраного постачальника. +`models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера +(OAuth/API key) або провести вас через ручне вставлення токена — залежно від того, +якого провайдера ви виберете. -`models auth login` запускає потік автентифікації Plugin постачальника (OAuth/API key). Використовуйте -`openclaw plugins list`, щоб побачити, які постачальники встановлено. +`models auth login` запускає потік автентифікації Plugin провайдера (OAuth/API key). Використовуйте +`openclaw plugins list`, щоб побачити, які провайдери встановлено. Використовуйте `openclaw models auth --agent `, щоб записати результати автентифікації до сховища конкретного налаштованого агента. Батьківський прапорець `--agent` підтримується в `add`, `login`, `setup-token`, `paste-token` і `login-github-copilot`. @@ -177,21 +182,21 @@ openclaw models auth login --provider openai-codex --set-default Примітки: -- `setup-token` і `paste-token` залишаються універсальними командами токенів для постачальників, +- `setup-token` і `paste-token` залишаються універсальними командами для токенів для провайдерів, які надають методи автентифікації за токеном. -- `setup-token` потребує інтерактивного TTY і запускає метод токен-автентифікації постачальника - (типово — метод `setup-token` цього постачальника, якщо він його надає). -- `paste-token` приймає рядок токена, згенерований в іншому місці або автоматизацією. +- `setup-token` потребує інтерактивного TTY і запускає метод токен-автентифікації провайдера + (за замовчуванням використовуючи метод `setup-token` цього провайдера, якщо він його надає). +- `paste-token` приймає рядок токена, згенерований деінде або автоматизацією. - `paste-token` потребує `--provider`, запитує значення токена та записує - його до id профілю за замовчуванням `:manual`, якщо ви не передасте + його до ID профілю за замовчуванням `:manual`, якщо ви не передасте `--profile-id`. - `paste-token --expires-in ` зберігає абсолютний строк дії токена на основі відносної тривалості, наприклад `365d` або `12h`. -- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- `setup-token` / `paste-token` Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. -## Пов’язано +## Пов’язане - [Довідка CLI](/uk/cli) - [Вибір моделі](/uk/concepts/model-providers) -- [Перемикання між моделями при збоях](/uk/concepts/model-failover) +- [Відмовостійкість моделей](/uk/concepts/model-failover) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 984d7cc8e..89b4a2fa3 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,188 +1,189 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресійних тестів для багів моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: модульні/e2e/live набори, ранери Docker і що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, виконавці Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-27T22:51:30Z" + generated_at: "2026-04-28T02:07:54Z" model: gpt-5.4 provider: openai - source_hash: f5adf6c223bc489d8c9eceb5a5a5b5b2c0fb774a48f6a71f6b793361e2fd4911 + source_hash: d2511d646a4e86fa0b7c17eb94dcc4931b88abb510a67f31e155f7da3f41279d source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір раннерів Docker. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір +виконавців Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані й вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем моделей/провайдерів. **Стек QA (qa-lab, qa-channel, live transport lanes)** задокументовано окремо: -- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, написання сценаріїв. +- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, створення сценаріїв. - [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`. -- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовується сценаріями на основі репозиторію. +- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, що використовується сценаріями з репозиторію. -Ця сторінка охоплює запуск звичайних тестових наборів і раннерів Docker/Parallels. Розділ із QA-специфічними раннерами нижче ([QA-специфічні раннери](#qa-specific-runners)) перелічує конкретні виклики `qa` і посилається назад на наведені вище довідкові матеріали. +Ця сторінка охоплює запуск звичайних наборів тестів і виконавців Docker/Parallels. Розділ про виконавці, специфічні для QA, нижче ([Виконавці, специфічні для QA](#qa-specific-runners)) перелічує конкретні виклики `qa` і посилається назад на наведені вище довідкові матеріали. ## Швидкий старт У більшості випадків: -- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Повний бар’єр перевірок (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Якщо ви працюєте над однією помилкою, спочатку віддавайте перевагу цільовим запускам. -- QA-сайт на базі Docker: `pnpm qa:lab:up` +- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Сайт QA на базі Docker: `pnpm qa:lab:up` - QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете отримати додаткову впевненість: +Коли ви змінюєте тести або хочете мати додаткову впевненість: -- Перевірка покриття: `pnpm test:coverage` +- Бар’єр покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потребує реальних облікових даних): +Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Огляд live-моделей у Docker: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід і невелику перевірку у стилі читання файлу. - Моделі, у чиїх метаданих заявлено вхід `image`, також виконують маленький хід із зображенням. - Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker sweep live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер запускає текстовий хід плюс невелику перевірку в стилі читання файлу. + Моделі, чиї метадані оголошують вхід `image`, також запускають невеликий хід із зображенням. + Вимкніть додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, що включає окремі матричні завдання Docker live model, - розподілені за провайдерами. - - Для точкових повторних запусків у CI викличте `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, що включає окремі Docker live model + matrix jobs, розшардовані за провайдером. + - Для цільових повторних запусків у CI dispatch-те `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - запланованих/релізних викликів. -- Димовий тест native Codex bound-chat: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний + викликів scheduled/release. +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane на шляху app-server Codex, прив’язує синтетичний Slack DM за допомогою `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення - проходять через native-прив’язку Plugin, а не через ACP. -- Димовий тест harness Codex app-server: `pnpm test:docker:live-codex-harness` - - Пропускає ходи агента Gateway через harness app-server, який належить Plugin, - перевіряє `/codex status` і `/codex models`, і за замовчуванням виконує перевірки image, - cron MCP, sub-agent і Guardian. Вимкніть перевірку sub-agent через - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex - app-server. Для точкової перевірки sub-agent вимкніть інші перевірки: + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення із зображенням + проходять через native binding Plugin, а не через ACP. +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` + - Запускає ходи агента Gateway через harness app-server Codex, що належить Plugin, + перевіряє `/codex status` і `/codex models`, а також типово виконує перевірки image, + cron MCP, sub-agent і Guardian. Вимкніть перевірку sub-agent за допомогою + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої + app-server Codex. Для цільової перевірки sub-agent вимкніть інші probes: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Це завершиться після перевірки sub-agent, якщо тільки не встановлено + Це завершується після перевірки sub-agent, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. -- Димовий тест rescue-команди Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Додаткова opt-in перевірка «belt-and-suspenders» для поверхні rescue-команд - message-channel. Вона виконує `/crestodian status`, ставить у чергу стійку зміну - моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Димовий тест Docker planner Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з підставним Claude CLI у `PATH` - і перевіряє, що резервний нечіткий planner перетворюється на audited typed +- Smoke перевірки команди rescue Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Додаткова opt-in перевірка «про всяк випадок» для поверхні команд rescue у message-channel. + Вона виконує `/crestodian status`, ставить у чергу постійну + зміну моделі, надсилає відповідь `/crestodian yes` і перевіряє шлях запису audit/config. +- Docker smoke планувальника Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що резервний fuzzy planner перетворюється на audited typed запис конфігурації. -- Димовий тест першого запуску Crestodian у Docker: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, спрямовує голий `openclaw` до +- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, маршрутизує bare `openclaw` до Crestodian, застосовує записи setup/model/agent/Discord Plugin + SecretRef, - валідує конфігурацію і перевіряє записи audit. Той самий шлях налаштування Ring 0 - також покрито в QA Lab через + валідує конфігурацію та перевіряє записи audit. Той самий шлях налаштування Ring 0 + також покривається в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Димовий тест вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім запустіть ізольований +- Smoke перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, а потім ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6, а - стенограма асистента зберігає нормалізоване `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6, а в + transcript помічника зберігається нормалізоване `usage.cost`. -Коли вам потрібен лише один збійний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. +Коли вам потрібен лише один проблемний випадок, віддавайте перевагу звуженню live-тестів за допомогою env-змінних allowlist, описаних нижче. -## QA-специфічні раннери +## Виконавці, специфічні для QA -Ці команди стоять поруч із основними тестовими наборами, коли вам потрібен реалізм QA-lab: +Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і -через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний dispatch із mock parity gate, live Matrix lane, +CI запускає QA Lab в окремих workflows. `Parity gate` запускається на відповідних PR і +з ручного dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного dispatch з mock parity gate, live Matrix lane, live Telegram lane під керуванням Convex і live Discord lane під керуванням Convex як -паралельними завданнями. Заплановані QA і релізні перевірки явно передають Matrix `--profile fast`, -тоді як CLI Matrix і стандартне значення ручного вводу workflow лишаються -`all`; ручний dispatch може розбивати `all` на завдання `transport`, `media`, `e2ee-smoke`, +паралельні jobs. Scheduled QA і release checks явно передають Matrix `--profile fast`, +тоді як Matrix CLI і значення manual workflow input за замовчуванням залишаються +`all`; ручний dispatch може шардити `all` на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -швидкі lane Matrix і Telegram перед схваленням релізу. +швидкі Matrix і Telegram lanes перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA на основі репозиторію безпосередньо на хості. - - За замовчуванням паралельно запускає кілька вибраних сценаріїв з ізольованими - worker-процесами Gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежену + - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими + працівниками Gateway. `qa-channel` типово використовує concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість worker-процесів, або `--concurrency 1` для старішого послідовного lane. - - Завершується з ненульовим кодом, якщо якийсь сценарій не вдається. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. + кількість працівників, або `--concurrency 1` для старого послідовного lane. + - Повертає ненульовий код завершення, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без помилкового коду завершення. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і макетів протоколу без заміни lane `mock-openai`, - орієнтованого на сценарії. + покриття fixture і protocol-mock без заміни lane `mock-openai`, + що враховує сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски прокидають підтримувані вхідні дані QA auth, практичні для гостьової системи: - ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, + - Live-запуски передають підтримувані QA auth inputs, які практично використовувати в guest: + ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають лишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтовану робочу область. - - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через + змонтований workspace. + - Записує звичайні QA report + summary, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської роботи з QA. + - Запускає сайт QA на базі Docker для операторської роботи з QA. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball із поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивне onboarding за API-ключем OpenAI, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, - запускає doctor і виконує один локальний хід агента проти змакованого endpoint OpenAI. + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний onboarding OpenAI API key, налаштовує Telegram + за замовчуванням, перевіряє, що увімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти mock OpenAI endpoint. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane - пакетного встановлення з Discord. + встановлення з пакета з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детермінований Docker smoke built-app для вбудованих стенограм - runtime context. Він перевіряє, що прихований runtime context OpenClaw зберігається як - нестандартне повідомлення, яке не відображається, замість витоку у видимий хід користувача, - а потім підкладає уражений пошкоджений session JSONL і перевіряє, що - `openclaw doctor --fix` переписує його в активну гілку з резервною копією. + - Запускає детермінований Docker smoke built-app для вбудованих runtime context + transcript. Він перевіряє, що прихований runtime context OpenClaw зберігається як + недемонстроване custom message замість витоку у видимий user turn, + потім підставляє уражений зламаний session JSONL і перевіряє, що + `openclaw doctor --fix` переписує його на активну гілку з резервною копією. - `pnpm test:docker:npm-telegram-live` - - Встановлює кандидата пакета OpenClaw у Docker, виконує onboarding - встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - live Telegram QA lane із цим встановленим пакетом як SUT Gateway. - - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть + - Встановлює кандидата пакета OpenClaw у Docker, виконує onboarding встановленого пакета, + налаштовує Telegram через встановлений CLI, а потім повторно використовує + live Telegram QA lane з цим встановленим пакетом як SUT Gateway. + - Типово використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або - `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати розв’язаний локальний tarball замість + `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати визначений локальний tarball замість встановлення з реєстру. - - Використовує ті самі облікові дані Telegram з env або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/релізу встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker-обгортка автоматично вибирає Convex. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільне + - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс + `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо + `OPENCLAW_QA_CONVEX_SITE_URL` і role secret Convex присутні в CI, + обгортка Docker автоматично вибирає Convex. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільну `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - - GitHub Actions також надає цей lane як ручний workflow для мейнтейнерів - `NPM Telegram Beta E2E`. Він не запускається при merge. Workflow використовує - середовище `qa-live-shared` і оренду облікових даних Convex CI. -- GitHub Actions також надає `Package Acceptance` для побічної перевірки продукту - проти одного кандидата пакета. Він приймає довірений ref, опубліковану npm-специфікацію, - URL HTTPS tarball плюс SHA-256 або артефакт tarball з іншого запуску, - завантажує нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає + - GitHub Actions також надає цей lane як ручний maintainer workflow + `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує + середовище `qa-live-shared` і оренду CI-облікових даних Convex. +- GitHub Actions також надає `Package Acceptance` для побічної product-перевірки + одного кандидата пакета. Він приймає довірений ref, опубліковану npm spec, + HTTPS tarball URL із SHA-256 або артефакт tarball з іншого run, завантажує + нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає наявний планувальник Docker E2E з профілями lane smoke, package, product, full або custom. Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити workflow Telegram QA - проти того самого артефакту `package-under-test`. - - Перевірка продукту для останньої beta: + проти того самого артефакта `package-under-test`. + - Остання beta product-перевірка: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -192,7 +193,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Перевірка точного URL tarball вимагає digest: +- Для перевірки точного tarball URL потрібен digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -202,7 +203,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Перевірка артефакта завантажує артефакт tarball з іншого запуску Actions: +- Перевірка артефакта завантажує артефакт tarball з іншого run Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -213,79 +214,80 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані channel/plugins через + - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає вбудовані channel/Plugin через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає невідсутніми runtime-залежності - неналаштованих Plugin, перший налаштований запуск Gateway або doctor встановлює - runtime-залежності кожного вбудованого Plugin за потреби, а другий перезапуск не - перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском - `openclaw update --tag `, і перевіряє, що - post-update doctor кандидата відновлює runtime-залежності вбудованого channel без - postinstall-відновлення з боку harness. + - Перевіряє, що виявлення налаштування залишає runtime-залежності + не налаштованих Plugin відсутніми, перший налаштований запуск Gateway або doctor + встановлює runtime-залежності кожного вбудованого Plugin за потреби, а другий + перезапуск не перевстановлює залежності, які вже були активовані. + - Також установлює відомий старіший npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що + post-update doctor кандидата відновлює runtime-залежності вбудованого channel + без postinstall-відновлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає smoke-тест оновлення native packaged-install у гостьових системах Parallels. Кожна - вибрана платформа спочатку встановлює запитаний baseline-пакет, потім виконує - встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє встановлену - версію, статус оновлення, готовність gateway і один локальний хід агента. - - Під час ітерацій над однією гостьовою системою використовуйте `--platform macos`, `--platform windows` або `--platform linux`. - Використовуйте `--json` для шляху до підсумкового артефакту та статусу - для кожного lane. - - Lane OpenAI за замовчуванням використовує `openai/gpt-5.5` для live-доказу - ходу агента. Передайте `--model ` або встановіть + - Запускає native smoke перевірки оновлення встановленого пакета у Parallels guests. Кожна + вибрана платформа спочатку встановлює запитаний baseline package, а потім запускає + команду встановленого `openclaw update` у тому ж guest і перевіряє + встановлену версію, статус оновлення, готовність gateway та один локальний + хід агента. + - Під час ітерацій над одним guest використовуйте `--platform macos`, `--platform windows` або `--platform linux`. + Використовуйте `--json` для шляху до summary artifact і статусу + кожного lane. + - За замовчуванням lane OpenAI використовує `openai/gpt-5.5` для live-перевірки ходу агента. + Передайте `--model ` або встановіть `OPENCLAW_PARALLELS_OPENAI_MODEL`, якщо навмисно перевіряєте іншу модель OpenAI. - - Обгортайте тривалі локальні запуски в host timeout, щоб зависання транспорту Parallels - не поглинули решту вікна тестування: + - Обгортайте довгі локальні запуски host timeout, щоб збої транспорту Parallels + не спожили решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. + - Скрипт записує вкладені журнали lane до `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж вважати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/відновлення - runtime-залежностей у «холодній» гостьовій системі; це все ще є нормальним станом, коли + - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor/ + відновлення runtime-залежностей у холодному guest; це все ще вважається нормальним станом, якщо вкладений журнал налагодження npm продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke-lane Parallels - для macOS, Windows або Linux. Вони використовують спільний стан VM і можуть конфліктувати під час - відновлення snapshot, видачі пакета або стану gateway у гостьовій системі. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke lanes Parallels + macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час + відновлення snapshot, видачі пакета або стану gateway guest. - Post-update proof запускає звичайну поверхню вбудованого Plugin, оскільки - фасади можливостей, як-от speech, image generation і media - understanding, завантажуються через вбудовані runtime API, навіть якщо сам + capability facades, такі як мовлення, генерація зображень і + розуміння медіа, завантажуються через вбудовані runtime API навіть тоді, коли сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. Лише для checkout вихідного коду — packaged installs не постачають `qa-lab`. - - Повний CLI, каталог profile/scenario, змінні середовища та розкладка артефактів: [Matrix QA](/uk/concepts/qa-matrix). + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. Лише checkout вихідного коду — встановлені пакети не постачають `qa-lab`. + - Повний CLI, каталог profile/scenario, env-змінні та структура artifact: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot з env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові оренди. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, при цьому SUT bot має мати видиме ім’я користувача Telegram. + - Підтримує `--credential-source convex` для спільних пулів облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути спільні оренди. + - Повертає ненульовий код завершення, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без помилкового коду завершення. + - Потребує двох різних ботів у тій самій приватній групі, при цьому SUT bot має мати Telegram username. - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати трафік ботів у групі. - - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. + - Записує Telegram QA report, summary і artifact observed-messages до `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостереженої відповіді SUT. -Live transport lanes мають спільний стандартний контракт, щоб нові транспорти не розходилися; матриця покриття для окремих lane міститься в [Огляд QA → Покриття live transport](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і не входить до цієї матриці. +Live transport lanes мають один спільний стандартний контракт, щоб нові транспорти не дрейфували; матриця покриття для кожного lane міститься в [QA overview → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і не є частиною цієї матриці. ### Спільні облікові дані Telegram через Convex (v1) -Коли для -`openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat для цієї оренди, поки lane виконується, і звільняє оренду під час завершення роботи. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: @@ -293,24 +295,24 @@ Live transport lanes мають спільний стандартний конт - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типове значення `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типове значення `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типове значення `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типове значення `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типове значення `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди мейнтейнера (додавання/видалення/перелік пулу) потребують +Команди адміністрування для maintainer (add/remove/list у пулі) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні команди CLI для мейнтейнерів: +CLI-хелпери для maintainer: ```bash pnpm openclaw qa credentials doctor @@ -319,9 +321,10 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайта Convex, секрети брокера, -префікс endpoint, HTTP timeout і доступність admin/list, не виводячи -секретні значення. Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, broker secrets, +префікс endpoint, HTTP timeout і доступність admin/list без виведення +секретних значень. Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI +утилітах. Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -352,40 +355,40 @@ pnpm openclaw qa credentials remove --credential-id - `groupId` має бути рядком із числовим ідентифікатором чату Telegram. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. -### Додавання каналу до QA +### Додавання channel до QA -Архітектура та назви допоміжних сценаріїв для нових адаптерів каналів наведені в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті Plugin, змонтувати як `openclaw qa ` і написати сценарії в `qa/scenarios/`. +Архітектура та назви scenario-helper для нових адаптерів channel описані в [QA overview → Adding a channel](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті Plugin, змонтувати як `openclaw qa ` і написати сценарії в `qa/scenarios/`. -## Тестові набори (що де запускається) +## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростаючий реалізм» (і зростаючу нестабільність/вартість): -### Unit / integration (типово) +### Unit / integration (типовий режим) - Команда: `pnpm test` -- Конфігурація: нетаргетовані запуски використовують набір шардованих конфігурацій `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації для окремих проєктів для паралельного планування -- Файли: core/unit інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit-тести виконуються в окремому шарді `unit-ui` +- Конфігурація: нецільові запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати шарди multi-project у конфігурації для кожного проєкту для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit-тести запускаються в окремому шарді `unit-ui` - Обсяг: - Чисті unit-тести - - In-process integration-тести (auth Gateway, маршрутизація, tooling, парсинг, конфігурація) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) + - Детерміновані регресійні тести для відомих багів - Очікування: - Запускається в CI - - Не потребує реальних ключів + - Реальні ключі не потрібні - Має бути швидким і стабільним - + - - Нетаргетований `pnpm test` запускає дванадцять менших шардованих конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на навантажених машинах і не дає роботам `auto-reply`/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл watch із кількома шардами не є практичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через scoped lane, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не змушує оплачувати повну вартість запуску root project. - - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lane: прямі редагування тестів, сусідні файли `*.test.ts`, явні зіставлення вихідного коду та локальні залежні елементи графа імпортів. Зміни config/setup/package не запускають тести широко, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` — це звичайний smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для доказу тестування викликайте `pnpm test:changed` або явний `pnpm test `. Оновлення версій лише в release metadata запускають цільові перевірки версій/config/root-dependency, із guard, який відхиляє зміни package поза полем version верхнього рівня. - - Зміни в live Docker ACP harness запускають точкові перевірки: синтаксис shell для live Docker auth-скриптів і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежено `scripts["test:docker:live-*"]`; зміни залежностей, export, version та іншої surface package усе ще використовують ширші guard. - - Unit-тести з малим імпортним навантаженням із agents, commands, plugins, допоміжних модулів auto-reply, `plugin-sdk` та подібних чистих утилітних областей спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lane. - - Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lane, тож редагування helper не змушують перезапускати повний важкий набір для цього каталогу. - - `auto-reply` має окремі бакети для допоміжних модулів core верхнього рівня, integration-тестів верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. У CI піддерево reply додатково ділиться на шарди agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими імпортами не володів усім Node tail. + - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу native root-project. Це зменшує піковий RSS на завантажених машинах і не дозволяє роботі auto-reply/extension заважати не пов’язаним наборам. + - `pnpm test --watch` усе ще використовує граф проєктів native root `vitest.config.ts`, оскільки цикл watch для багатьох шардів є непрактичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві scoped lanes: прямі зміни тестів, сусідні файли `*.test.ts`, явні source mappings і локальні dependents графа імпортів. Зміни config/setup/package не запускають широкі тести, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — звичайний розумний локальний бар’єр перевірок для вузьких змін. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для доказу тестування викликайте `pnpm test:changed` або явний `pnpm test `. Підвищення версії лише в metadata релізу запускає цільові перевірки version/config/root-dependency, із guard, який відхиляє зміни package поза полем версії верхнього рівня. + - Зміни в live Docker ACP harness запускають цільові перевірки: shell syntax для live Docker auth-скриптів і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни dependency, export, version та інших поверхонь package і далі використовують ширші guard. + - Unit-тести з легкими імпортами для agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed mode з явними сусідніми тестами в цих легких lanes, тому зміни helper уникають повторного запуску всього важкого набору для цього каталогу. + - `auto-reply` має окремі bucket для top-level core helpers, top-level integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими імпортами не контролював увесь хвіст Node. @@ -393,54 +396,54 @@ pnpm openclaw qa credentials remove --credential-id - Коли ви змінюєте входи виявлення message-tool або runtime context для Compaction, зберігайте обидва рівні покриття. - - Додавайте точкові helper-регресії для чистих меж маршрутизації та - нормалізації. - - Підтримуйте здоровий стан інтеграційних наборів embedded runner: + - Додавайте цільові регресійні тести helper для чистих меж + маршрутизації та нормалізації. + - Підтримуйте в робочому стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction як і раніше проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести - не є достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped id і поведінка Compaction, як і раніше, проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише на рівні helper + не є достатньою заміною для цих integration-шляхів. - + - - Базова конфігурація Vitest за замовчуванням використовує `threads`. + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - non-isolated runner у root project, e2e та live config. - - Root UI lane зберігає свій `jsdom` setup та optimizer, але теж працює на - спільному non-isolated runner. - - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + неізольований runner у root projects, e2e і live config. + - Root lane UI зберігає свій `jsdom` setup і optimizer, але теж працює на + спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - + - - `pnpm changed:lanes` показує, які архітектурні lane зачіпає diff. - - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно додає до staging відформатовані файли і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли - вам потрібен smart local check gate. - - `pnpm test:changed` за замовчуванням маршрутизує через дешеві scoped lane. Використовуйте - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише коли агент - вирішує, що редагування harness, config, package або contract справді потребує ширшого + - Явно запускайте `pnpm check:changed` перед передачею або push, коли вам + потрібен розумний локальний бар’єр перевірок. + - `pnpm test:changed` типово маршрутизує через дешеві scoped lanes. Використовуйте + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент + вирішує, що зміна harness, config, package або contract справді потребує ширшого покриття Vitest. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму логіку маршрутизації, - лише з вищою межею worker. - - Автомасштабування локальних worker навмисно консервативне і зменшується, - коли середнє навантаження хоста вже високе, тож кілька одночасних - запусків Vitest за замовчуванням шкодять менше. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в changed-mode лишалися коректними, коли змінюється - обв’язка тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, + лише з вищою межею кількості workers. + - Автоматичне масштабування локальних workers навмисно є консервативним і знижує навантаження, + коли середнє навантаження хоста вже високе, тому кілька одночасних + запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/файли конфігурації як + `forceRerunTriggers`, щоб повторні запуски в режимі changed mode залишалися коректними, коли + змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. @@ -448,82 +451,82 @@ pnpm openclaw qa credentials remove --credential-id - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс - вивід import-breakdown. - - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд - файлами, зміненими з часу `origin/main`. - - Дані про час виконання шардів записуються в `.artifacts/vitest-shard-timings.json`. - Запуски всієї конфігурації використовують шлях до config як ключ; CI-шарди - за include-pattern додають назву шарда, щоб можна було окремо - відстежувати відфільтровані шарди. + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс + вивід розбивки імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, + зміненими відносно `origin/main`. + - Дані про час виконання shard записуються в `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях конфігурації як ключ; шарди CI + з include-pattern додають назву shard, щоб відфільтровані шарди можна було + відстежувати окремо. - Коли один «гарячий» тест усе ще витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - напряму макетуйте цей seam замість глибокого імпорту runtime-helper, лише - щоб передати їх через `vi.mock(...)`. + напряму мокайте цей seam замість глибокого імпорту runtime helper лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з native root-project path для цього зафіксованого + `test:changed` із native root-project path для цього зафіксованого diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне - незакомічене дерево, маршрутизуючи список змінених файлів через + - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного + брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для - старту Vitest/Vite і transform overhead. - - `pnpm test:perf:profile:runner` записує профілі runner CPU+heap для - unit-набору з вимкненим паралелізмом файлів. + - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для + старту Vitest/Vite і накладних витрат transform. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для + unit-набору з вимкненим паралелізмом по файлах. -### Стабільність (Gateway) +### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою - - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Виконує запит до `diagnostics.stability` через WS RPC Gateway - - Покриває helper-модулі збереження diagnostic stability bundle - - Перевіряє, що recorder лишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибина черги для кожної сесії знову зменшується до нуля + - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням + - Пропускає синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій + - Виконує запит `diagnostics.stability` через Gateway WS RPC + - Охоплює helper збереження diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибини черг для кожної сесії знову спадають до нуля - Очікування: - Безпечно для CI і без ключів - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (Gateway smoke) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` - Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і в решті репозиторію. - - Використовує адаптивних worker (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити витрати на I/O консолі. + - Використовує адаптивних workers (CI: до 2, локально: типово 1). + - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker (обмеження 16). + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing Node і важча мережева взаємодія - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) - - Не потребує реальних ключів + - Запускається в CI (коли увімкнено в pipeline) + - Реальні ключі не потрібні - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: OpenShell backend smoke +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований gateway OpenShell на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Запускає ізольований OpenShell gateway на хості через Docker + - Створює sandbox з тимчасового локального Dockerfile + - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє канонічну поведінку віддаленої файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і справного демона Docker + - Потребує локального CLI `openshell` і справного Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний двійковий файл CLI або wrapper-script + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) @@ -532,206 +535,206 @@ pnpm openclaw qa credentials remove --credential-id - Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin у `extensions/` - Типове значення: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки rate limit + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає rate limits + - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасову тестову home-директорію, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували вашу реальну home-директорію. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. -- Ротація API-ключів (залежно від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу при відповідях із rate limit. +- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові журнали. +- Ротація API-ключів (залежно від провайдера): встановлюйте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні навіть тоді, коли перехоплення консолі Vitest приглушене. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway одразу передаються під час live-запусків. - - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера помітно активні, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway відразу транслювалися під час live-запусків. + - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який набір мені запускати? +## Який набір слід запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) -- Торкаєтеся мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / специфічні збої провайдера / виклик інструментів: запускайте звужений `pnpm test:live` ## Live-тести (що торкаються мережі) -Для live-матриці моделей, smoke-тестів бекенда CLI, smoke-тестів ACP, harness -Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також обробки облікових даних для live-запусків — див. +Для live-матриці моделей, smoke перевірок backend CLI, ACP smoke, harness +app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також для обробки облікових даних у live-запусках — див. [Тестування — live-набори](/uk/help/testing-live). -## Раннери Docker (необов’язкові перевірки «працює в Linux») +## Виконавці Docker (необов’язкові перевірки «працює в Linux») -Ці раннери Docker поділяються на дві групи: +Ці виконавці Docker поділяються на дві групи: -- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл свого ключа профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням мають менший smoke-ліміт, щоб повний Docker-огляд залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Виконавці live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (а також завантажують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Виконавці Docker live за замовчуванням мають менший ліміт smoke, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env var, коли + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає Docker-образ live через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише раннер Node/Git для lane встановлення/оновлення/залежностей Plugin; ці lane монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для lane функціональності built-app. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким lane live, npm-install і multi-service запускатися всі одночасно. Якщо один lane важчий за активні обмеження, планувальник все одно може запустити його, коли пул порожній, а потім тримає його запущеним окремо, доки знову не з’явиться доступна місткість. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли хост Docker має більший запас ресурсів. Раннер за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає час виконання успішних lane в `.artifacts/docker-tests/lane-timings.json` і використовує ці часові дані, щоб у наступних запусках першими стартували довші lane. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збірки чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб вивести CI-план для вибраних lane, потреб package/image і облікових даних. -- `Package Acceptance` — це GitHub-native перевірка пакета для питання «чи працює цей installable tarball як продукт?». Вона визначає один кандидат пакета з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає повторно використовувані Docker E2E lane проти саме цього tarball, замість повторного пакування вибраного ref. `workflow_ref` вибирає trusted workflow/harness scripts, а `package_ref` вибирає вихідний commit/branch/tag для пакування, коли `source=ref`; це дає змогу поточній логіці acceptance перевіряти старі trusted commit. Профілі впорядковано за шириною охоплення: `smoke` — це швидке встановлення/channel/agent плюс gateway/config, `package` — це контракт package/update/plugin і типовий native replacement для більшості покриття package/update у Parallels, `product` додає MCP channels, очищення cron/subagent, OpenAI web search і OpenWebUI, а `full` запускає Docker-частини release-path з OpenWebUI. Валідація релізу запускає власну package delta (`bundled-channel-deps-compat plugins-offline`) плюс Telegram package QA, оскільки Docker-частини release-path уже покривають overlap lane package/update/plugin. Цільові команди повторного запуску GitHub Docker, згенеровані з артефактів, включають попередній артефакт пакета та підготовлені входи image, коли вони доступні, тож збійні lane можуть уникнути повторної збірки пакета й образів. -- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичним built graph від `dist/entry.js` і `dist/cli/run-main.js` та завершується з помилкою, якщо до command dispatch startup імпортує залежності package, як-от Commander, prompt UI, undici або logging. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, schema config і команду model-list. -- Legacy compatibility у Package Acceptance обмежено версією `2026.4.25` (включно з `2026.4.25-beta.*`). До цього порогу harness допускає лише прогалини в метаданих shipped-package: пропущені приватні записи інвентарю QA, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, похідному від tarball, відсутній збережений `update.channel`, застарілі розташування install-record Plugin, відсутнє збереження install-record marketplace і міграцію метаданих config під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи є суворими помилками. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два image `scripts/e2e/Dockerfile`. Базовий image — це лише виконавець Node/Git для lane встановлення/оновлення/залежностей Plugin; ці lanes монтують попередньо зібраний tarball. Функціональний image встановлює той самий tarball у `/app` для lane функціональності built-app. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а ліміти ресурсів не дозволяють усім важким live, npm-install і multi-service lanes стартувати одночасно. Якщо один lane важчий за активні ліміти, scheduler все одно може запустити його, коли пул порожній, і потім триматиме його запущеним окремо, доки знову не з’явиться доступна ємність. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більший запас ресурсів. За замовчуванням runner виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, виводить статус кожні 30 секунд, зберігає час виконання успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці дані, щоб у наступних запусках спочатку стартували довші lanes. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збірки або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб вивести план CI для вибраних lane, потреб package/image та облікових даних. +- `Package Acceptance` — це нативний для GitHub бар’єр перевірки пакета для питання «чи працює цей встановлюваний tarball як продукт?». Він визначає один кандидат пакета з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає повторно використовувані Docker E2E lanes проти саме цього tarball замість повторного пакування вибраного ref. `workflow_ref` вибирає довірені workflow/скрипти harness, а `package_ref` вибирає вихідний commit/branch/tag для пакування, коли `source=ref`; це дозволяє поточній логіці acceptance перевіряти старіші довірені commit. Профілі впорядковано за шириною охоплення: `smoke` — це швидке встановлення/channel/agent плюс gateway/config, `package` — це контракт package/update/Plugin і типова native заміна для більшості покриття package/update Parallels, `product` додає MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI, а `full` запускає Docker-частини шляху release з OpenWebUI. Перевірка release запускає спеціальну різницю package (`bundled-channel-deps-compat plugins-offline`) плюс Telegram package QA, оскільки Docker-частини шляху release вже покривають суміжні lanes package/update/Plugin. Цільові команди повторного запуску GitHub Docker, згенеровані з artifact, включають попередні входи artifact пакета та підготовленого image, коли вони доступні, тому для невдалих lane можна уникнути повторної збірки пакета та image. +- Перевірки build і release запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичним зібраним графом від `dist/entry.js` і `dist/cli/run-main.js` і завершується з помилкою, якщо імпорти старту до dispatch статично імпортують залежності package, такі як Commander, prompt UI, undici або logging, до dispatch команди; він також утримує зібраний run chunk gateway у межах бюджету й відхиляє статичні імпорти відомих холодних шляхів gateway. Smoke перевірки пакованого CLI також охоплюють root help, onboard help, doctor help, status, schema config і команду списку моделей. +- Legacy-сумісність `Package Acceptance` обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness терпимо ставиться лише до прогалин у метаданих shipped-package: пропущені приватні записи інвентарю QA, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, похідному від tarball, відсутній збережений `update.channel`, застарілі розташування записів встановлення Plugin, відсутнє збереження записів встановлення marketplace і міграція метаданих config під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи вважаються суворими помилками. +- Виконавці container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-раннери live-моделей також монтують лише потрібні home-каталоги auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home-каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище auth на хості: +Виконавці Docker для live-моделей також bind-mount лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Димовий тест ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням покриває Claude, Codex і Gemini, із суворим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- Димовий тест бекенда CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Димовий тест harness Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, із суворим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) +- Smoke перевірка CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke перевірка harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Димовий тест observability: `pnpm qa:otel:smoke` — це приватний QA lane для checkout вихідного коду. Він навмисно не входить до Docker lane релізу пакетів, оскільки npm tarball не містить QA Lab. -- Димовий тест live Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Димовий тест onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding env-ref і за замовчуванням Telegram, перевіряє, що doctor відновлює runtime deps активованого Plugin, і виконує один змакований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змінюйте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Димовий тест перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений channel і роботу Plugin після оновлення, а потім повертається до package `stable` і перевіряє статус оновлення. -- Димовий тест session runtime context: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого стенографічного runtime context, а також doctor-відновлення для уражених дубльованих гілок prompt-rewrite. -- Димовий тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home-каталозі й перевіряє, що `openclaw infer image providers --json` повертає вбудовані image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Димовий тест інсталятора в Docker: `bash scripts/test-install-sh-docker.sh` використовує спільний npm-кеш для своїх контейнерів root, update і direct-npm. Димовий тест оновлення за замовчуванням використовує npm `latest` як stable baseline перед оновленням до tarball кандидата. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, або через вхід `update_baseline_version` workflow Install Smoke у GitHub. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб root-owned записи кешу не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. -- CI Install Smoke пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цього env, коли потрібне покриття прямого `npm install -g`. -- Димовий тест CLI для видалення спільного workspace агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає образ root Dockerfile, створює два агенти з одним workspace в ізольованому home-каталозі контейнера, запускає `agents delete --json` і перевіряє коректний JSON та поведінку зі збереженим workspace. Повторно використовуйте образ install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Димовий тест browser CDP snapshot: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає вихідний E2E-образ плюс шар Chromium, запускає Chromium з сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshots ролі CDP покривають URL посилань, clickables із просунутим курсором, refs iframe і метадані frame. -- Мінімальна reasoning-регресія для OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змакований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення provider schema і перевіряє, що сирі подробиці з’являються в журналах Gateway. -- Міст каналу MCP (seeded Gateway + stdio bridge + димовий тест raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти Pi bundle MCP (реальний stdio MCP server + димовий тест allow/deny для профілю embedded Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (димовий тест встановлення, встановлення/видалення ClawHub, оновлення marketplace і ввімкнення/перевірка Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Встановіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначайте типовий package через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. -- Димовий тест Plugin update unchanged: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Димовий тест метаданих config reload: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний агрегат Docker і частини release-path bundled-channel один раз попередньо пакують цей tarball, а потім розбивають перевірки bundled channel на незалежні lane, включно з окремими lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Частини релізу розділяють димові тести каналів, цілі оновлення та контракти setup/runtime на `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`; агрегатний блок `bundled-channels` лишається доступним для ручних повторних запусків. Workflow релізу також розділяє частини installer провайдерів і частини встановлення/видалення вбудованих Plugin; застарілі частини `package-update`, `plugins-runtime` і `plugins-integrations` лишаються агрегатними псевдонімами для ручних повторних запусків. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. -- Звужуйте runtime deps вбудованих Plugin під час ітерації, вимикаючи непов’язані сценарії, наприклад: +- Smoke перевірка спостережуваності: `pnpm qa:otel:smoke` — це приватний lane QA для checkout вихідного коду. Його навмисно не включено до Docker lane релізу пакета, оскільки npm tarball не містить QA Lab. +- Smoke перевірка live Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke перевірка onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding env-ref плюс Telegram за замовчуванням, перевіряє, що doctor відновлює runtime-залежності активованого Plugin, і запускає один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову хоста через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або змініть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke перевірка перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений channel і роботу Plugin після оновлення, а потім перемикається назад на package `stable` і перевіряє статус оновлення. +- Smoke перевірка runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого transcript runtime context плюс відновлення doctor для уражених дубльованих гілок prompt-rewrite. +- Smoke перевірка глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів image замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку хоста через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, або скопіюйте `dist/` зі зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує спільний кеш npm для своїх контейнерів root, update і direct-npm. Smoke перевірка оновлення типово використовує npm `latest` як стабільний baseline перед оновленням до tarball кандидата. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, або через вхід `update_baseline_version` workflow Install Smoke на GitHub. Перевірки installer без root зберігають ізольований кеш npm, щоб записи кешу, які належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними перезапусками. +- Install Smoke CI пропускає дубльоване пряме глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Smoke перевірка CLI для видалення agents із shared workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає root Dockerfile image, створює два agent із одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON та поведінку зі збереженням workspace. Повторно використовуйте image install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Мережа Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Smoke перевірка snapshot Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає вихідний E2E image плюс шар Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshot ролі CDP охоплюють URL посилань, clickables, підняті курсором, iframe refs і метадані frame. +- Мінімальна регресійна перевірка reasoning OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` із `minimal` до `low`, потім примусово викликає відхилення schema провайдера і перевіряє, що сирі деталі з’являються в журналах Gateway. +- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP пакета Pi (реальний stdio MCP server + smoke перевірка allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke перевірка встановлення, встановлення/видалення ClawHub, оновлення marketplace і ввімкнення/перевірка пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Встановіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначте package за замовчуванням через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. +- Smoke перевірка незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke перевірка метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованого Plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker image runner, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову хоста після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний агрегат Docker і частини bundled-channel шляху релізу попередньо пакують цей tarball один раз, а потім розбивають перевірки bundled channel на незалежні lanes, включно з окремими lanes оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Частини релізу поділяють smoke перевірки channel, цілі оновлення та контракти setup/runtime на `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`; агрегатна частина `bundled-channels` залишається доступною для ручних повторних запусків. Workflow релізу також поділяє частини installer провайдерів і частини встановлення/видалення вбудованих Plugin; застарілі частини `package-update`, `plugins-runtime` і `plugins-integrations` залишаються агрегатними псевдонімами для ручних повторних запусків. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю channel під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Звужуйте runtime-залежності вбудованого Plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати та повторно використовувати спільний функціональний образ: +Щоб вручну попередньо зібрати та повторно використати спільний функціональний image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime built-app. +Перевизначення image для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, як і раніше, мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Тести QR та installer у Docker зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime built-app. -Docker-раннери live-моделей також монтують поточний checkout лише для читання і -переміщують його в тимчасовий workdir усередині контейнера. Це зберігає -runtime-образ компактним, але водночас запускає Vitest точно проти вашого локального source/config. -Крок переміщення пропускає великі локальні кеші та результати збірки застосунків, як-от +Виконавці Docker для live-моделей також bind-mount поточний checkout у режимі лише для читання і +розгортають його в тимчасовий workdir всередині контейнера. Це дозволяє зберігати runtime +image компактним, але все одно запускати Vitest проти вашого точного локального вихідного коду/config. +Крок розгортання пропускає великі локальні кеші та артефакти збірки застосунку, такі як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -справжні worker-процеси каналів Telegram/Discord/etc. усередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway -live із цього Docker lane. -`test:docker:openwebui` — це суміснісний smoke-тест вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint, +вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +машинно-специфічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки gateway не запускали +реальні працівники channel Telegram/Discord/etc. усередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live-покриття з цього Docker lane. +`test:docker:openwebui` — це суміснісна smoke перевірка вищого рівня: вона запускає +контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -образу Open WebUI, а сам Open WebUI — завершення власного холодного старту. -Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — це основний спосіб надати його в Dockerized-запусках. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити +image Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. +Цей lane очікує наявність придатного live-ключа моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує +`test:docker:mcp-channels` навмисно є детермінованим і не потребує реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє маршрутизоване виявлення розмов, читання стенограм, метадані вкладень, -поведінку live event queue, маршрутизацію вихідного надсилання та сповіщення каналу + -дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -напряму досліджує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що +контейнер, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення в стилі Claude про channel + +дозволи через реальний міст stdio MCP. Перевірка сповіщень +безпосередньо перевіряє сирі кадри stdio MCP, тож smoke перевірка валідує те, що міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live-моделі. -Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей сервер через runtime embedded Pi bundle -MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live- +ключа моделі. Він збирає Docker image репозиторію, запускає реальний сервер перевірки stdio MCP +усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP пакета Pi, +виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live- +ключа моделі. Він запускає seeded Gateway з реальним сервером перевірки stdio MCP, виконує +ізольований хід cron і one-shot дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke-тест ACP thread природною мовою (не CI): +Ручна smoke перевірка ACP thread простою мовою (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для валідації маршрутизації ACP thread, тому не видаляйте його. -Корисні env var: +Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (типове значення: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типове значення: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типове значення: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env var, отримані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішніх auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типове значення: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли auth CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і завантажується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, завантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування автентифікації зовнішніх CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke-тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt із перевіркою nonce, який використовує smoke-тест Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілю (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke перевірки Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke перевірка Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI -## Перевірка документації +## Перевірка коректності документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків усередині сторінок: `pnpm docs:check-links:anchors`. +Після змін у документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну валідацію якірних посилань Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Offline-регресії (безпечні для CI) +## Офлайн-регресії (безпечні для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Tool calling Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + примусово застосовує auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (змоканий OpenAI, реальний цикл gateway + агент): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Evals надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності агента»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесії та вплив на config (`src/gateway/gateway.test.ts`). +- Змоканий виклик інструментів через реальний цикл gateway + агент (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють підключення сесії та вплив на config (`src/gateway/gateway.test.ts`). -Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і виконує обов’язкові кроки/аргументи? +- **Вибір:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/аргументів? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають спочатку лишатися детермінованими: +Майбутні evals мають спочатку залишатися детермінованими: -- Раннер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів Skill і wiring сесії. -- Невеликий набір сценаріїв, орієнтованих на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, під контролем env) лише після того, як з’явиться безпечний для CI набір. +- Виконавець сценаріїв, що використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і підключення сесії. +- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live evals (opt-in, з керуванням через env) — лише після того, як буде готовий безпечний для CI набір. ## Контрактні тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені Plugin і запускають набір +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає +своєму інтерфейсному контракту. Вони проходять по всіх виявлених plugins і запускають набір перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці файли спільних seam і smoke; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +пропускає ці файли спільних seam і smoke; запускайте команди контрактів явно, +коли змінюєте спільні поверхні channel або провайдера. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` ### Контракти channel @@ -742,24 +745,24 @@ MCP, виконує інструмент, а потім перевіряє, що - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка ID thread -- **directory** - API каталогу/реєстру +- **actions** - Обробники дій channel +- **threading** - Обробка thread ID +- **directory** - API каталогу/складу - **group-policy** - Застосування групової політики -### Контракти статусу provider +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу каналу +- **status** - Перевірки статусу channel - **registry** - Форма реєстру Plugin -### Контракти provider +### Контракти провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/добір автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin @@ -769,26 +772,26 @@ MCP, виконує інструмент, а потім перевіряє, що ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни channel чи provider Plugin +- Після зміни експортів або підшляхів plugin-sdk +- Після додавання або зміни channel чи Plugin провайдера - Після рефакторингу реєстрації або виявлення Plugin Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену у live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдер або фіксацію точного перетворення форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), зберігайте live-тест вузьким і opt-in через env var -- Віддавайте перевагу націлюванню на найменший шар, який виявляє баг: - - баг перетворення/відтворення запиту провайдера → тест прямих моделей - - баг у pipeline сесії/історії/tool Gateway → live smoke Gateway або безпечний для CI mock-тест Gateway -- Захисний механізм обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точного перетворення форми запиту) +- Якщо проблема за своєю природою лише для live (rate limit, політики auth), зберігайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому рівню, який вловлює баг: + - баг перетворення/повторення запиту провайдера → тест прямих моделей + - баг конвеєра сесії/історії/інструментів gateway → live smoke gateway або безпечний для CI mock-тест gateway +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id із сегментами обходу відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. -## Пов’язане +## Пов’язані матеріали - [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci) diff --git a/docs/uk/plugins/compatibility.md b/docs/uk/plugins/compatibility.md index 837c44e3e..076538204 100644 --- a/docs/uk/plugins/compatibility.md +++ b/docs/uk/plugins/compatibility.md @@ -1,45 +1,61 @@ --- read_when: - - Ви підтримуєте плагін OpenClaw - - Ви бачите попередження про сумісність плагіна - - Ви плануєте міграцію SDK плагіна або маніфесту + - Ви підтримуєте Plugin OpenClaw + - Ви бачите попередження про сумісність Plugin + - Ви плануєте міграцію SDK або маніфесту Plugin summary: Контракти сумісності Plugin, метадані застарівання та очікування щодо міграції title: Сумісність Plugin x-i18n: - generated_at: "2026-04-28T01:06:39Z" + generated_at: "2026-04-28T02:07:57Z" model: gpt-5.4 provider: openai - source_hash: 9cb004d9959f1892f3bebcdfb9bee3fd78fc3322a2cbee4e8078c41a3f6706c6 + source_hash: eecf94743cf34c5b773bfa8066164f90b7c8a75667c43f3f1002d32ec1d04902 source_path: plugins/compatibility.md workflow: 15 --- -OpenClaw зберігає старі контракти Plugin підключеними через іменовані адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані та зовнішні плагіни, поки розвиваються контракти SDK, маніфесту, налаштування, конфігурації та середовища виконання агента. +OpenClaw зберігає старі контракти Plugin, підключені через іменовані +адаптери сумісності, перш ніж видаляти їх. Це захищає наявні вбудовані та зовнішні +Plugin, поки розвиваються контракти SDK, маніфесту, налаштування, конфігурації +та середовища виконання агента. ## Реєстр сумісності Контракти сумісності Plugin відстежуються в основному реєстрі за адресою `src/plugins/compat/registry.ts`. -Кожен запис містить: +Кожен запис має: - стабільний код сумісності - статус: `active`, `deprecated`, `removal-pending` або `removed` -- власник: SDK, config, setup, channel, provider, виконання Plugin, середовище виконання агента або core -- дати впровадження та застарівання, де це застосовно +- власника: SDK, config, setup, channel, provider, виконання plugin, середовище виконання агента + або core +- дати запровадження та застарівання, коли це застосовно - вказівки щодо заміни -- документацію, діагностику й тести, що охоплюють стару та нову поведінку +- документацію, діагностику та тести, які охоплюють стару й нову поведінку -Реєстр є джерелом для планування супроводу та майбутніх перевірок інспектора Plugin. Якщо змінюється поведінка, видима для плагіна, додайте або оновіть запис сумісності в тій самій зміні, що додає адаптер. +Реєстр є джерелом для планування супровідниками та майбутніх перевірок +інспектора Plugin. Якщо змінюється поведінка, видима для Plugin, додайте або +оновіть запис сумісності в тій самій зміні, що додає адаптер. -Сумісність Doctor repair і міграцій відстежується окремо в -`src/commands/doctor/shared/deprecation-compat.ts`. Ці записи охоплюють старі форми config, структури install-ledger і repair shim, які можуть знадобитися й після видалення шляху сумісності в середовищі виконання. +Сумісність виправлень doctor і міграцій відстежується окремо в +`src/commands/doctor/shared/deprecation-compat.ts`. Ці записи охоплюють старі +форми config, макети журналу встановлення та shim-сумісності для виправлень, які +може знадобитися залишити доступними після видалення шляху сумісності середовища виконання. -Під час перевірок релізу слід перевіряти обидва реєстри. Не видаляйте міграцію doctor лише тому, що відповідний запис сумісності середовища виконання або config втратив чинність; спершу переконайтеся, що немає підтримуваного шляху оновлення, якому все ще потрібне це виправлення. Також повторно перевіряйте кожну анотацію заміни під час планування релізу, оскільки власність Plugin і охоплення config можуть змінюватися, коли provider і channel виносяться з core. +Під час перевірок перед релізом слід перевіряти обидва реєстри. Не видаляйте +міграцію doctor лише тому, що відповідний запис сумісності середовища виконання +або config втратив чинність; спочатку переконайтеся, що більше немає +підтримуваного шляху оновлення, який усе ще потребує цього виправлення. Також +повторно перевіряйте кожну анотацію заміни під час планування релізу, оскільки +власність Plugin і обсяг config можуть змінюватися, коли provider і channel +виносяться з core. ## Пакет інспектора Plugin -Інспектор Plugin має жити поза основним репозиторієм OpenClaw як окремий пакет/репозиторій, що спирається на версійовані контракти сумісності та маніфесту. +Інспектор Plugin має розміщуватися поза основним репозиторієм OpenClaw як +окремий пакет/репозиторій, що спирається на версійовані контракти сумісності +та маніфесту. CLI першого дня має бути таким: @@ -49,77 +65,110 @@ openclaw-plugin-inspector ./my-plugin Він має виводити: -- перевірку маніфесту/схеми -- версію контракту сумісності, яка перевіряється +- валідацію маніфесту/схеми +- версію сумісності контракту, яка перевіряється - перевірки метаданих встановлення/джерела - перевірки імпорту холодного шляху - попередження про застарівання та сумісність -Використовуйте `--json` для стабільного машинозчитуваного виводу в анотаціях CI. Ядро OpenClaw має надавати контракти та фікстури, які інспектор може використовувати, але не повинно публікувати бінарний файл інспектора з основного пакета `openclaw`. +Використовуйте `--json` для стабільного машиночитаного виводу в анотаціях CI. Core +OpenClaw має надавати контракти та фікстури, які може споживати інспектор, але +не має публікувати бінарний файл інспектора з основного пакета `openclaw`. + +### Доріжка приймання для супровідників + +Використовуйте Blacksmith Testbox для доріжки приймання пакета, що встановлюється, під час валідації +зовнішнього інспектора щодо пакетів Plugin OpenClaw. Запускайте її з чистого +checkout OpenClaw після збирання пакета: + +```sh +blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 +blacksmith testbox run --id "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json" +blacksmith testbox run --id "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json" +blacksmith testbox run --id "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- --json" +blacksmith testbox stop +``` + +Зберігайте цю доріжку як opt-in для супровідників, оскільки вона встановлює +зовнішній npm-пакет і може перевіряти пакети Plugin, клоновані поза репозиторієм. Локальні +захисні механізми репозиторію охоплюють export map SDK, метадані реєстру +сумісності, поступове виведення з ужитку застарілих SDK-import, а також межі імпорту +вбудованих extension; перевірка інспектором у Testbox охоплює пакет у тому +вигляді, як його споживають автори зовнішніх Plugin. ## Політика застарівання -OpenClaw не повинен видаляти задокументований контракт Plugin у тому самому релізі, який запроваджує його заміну. +OpenClaw не має видаляти задокументований контракт Plugin у тому самому релізі, +який запроваджує його заміну. Послідовність міграції така: -1. Додати новий контракт. -2. Залишити стару поведінку підключеною через іменований адаптер сумісності. -3. Виводити діагностику або попередження, коли автори плагінів уже можуть діяти. -4. Задокументувати заміну й часові межі. -5. Протестувати як старий, так і новий шляхи. -6. Дочекатися завершення оголошеного вікна міграції. -7. Видаляти лише з явним схваленням для релізу, що ламає сумісність. +1. Додайте новий контракт. +2. Залиште стару поведінку підключеною через іменований адаптер сумісності. +3. Видавайте діагностику або попередження, коли автори Plugin можуть діяти. +4. Задокументуйте заміну та часові межі. +5. Протестуйте і старий, і новий шляхи. +6. Зачекайте протягом оголошеного вікна міграції. +7. Видаляйте лише з явним схваленням для релізу з несумісними змінами. -Записи зі статусом deprecated мають містити дату початку попереджень, заміну, посилання на документацію та остаточну дату видалення не пізніше ніж через три місяці після початку попереджень. Не додавайте застарілий шлях сумісності з відкритим вікном видалення, якщо супровідники явно не вирішили, що це постійна сумісність, і не позначили його як `active`. +Застарілі записи мають включати дату початку попередження, заміну, посилання на +документацію та кінцеву дату видалення не пізніше ніж через три місяці після +початку попередження. Не додавайте застарілий шлях сумісності з відкритим +терміном видалення, якщо супровідники явно не вирішили, що це постійна +сумісність, і не позначили його як `active`. ## Поточні області сумісності Поточні записи сумісності включають: - застарілі широкі імпорти SDK, такі як `openclaw/plugin-sdk/compat` -- застарілі форми Plugin лише з hook і `before_agent_start` -- застарілі точки входу Plugin `activate(api)`, поки плагіни мігрують на +- застарілі форми Plugin лише з hook та `before_agent_start` +- застарілі точки входу Plugin `activate(api)`, поки Plugin мігрують на `register(api)` - застарілі псевдоніми SDK, такі як `openclaw/extension-api`, - `openclaw/plugin-sdk/channel-runtime`, конструктори статусу `openclaw/plugin-sdk/command-auth`, - `openclaw/plugin-sdk/test-utils` (замінений на цільові підшляхи тестів - `openclaw/plugin-sdk/*`), а також псевдоніми типів `ClawdbotConfig` / + `openclaw/plugin-sdk/channel-runtime`, конструктори status + `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/test-utils` (замінені на цільові + підшляхи тестів `openclaw/plugin-sdk/*`), а також псевдоніми типів `ClawdbotConfig` / `OpenClawSchemaType` -- allowlist вбудованих Plugin і поведінку ввімкнення +- поведінка allowlist і ввімкнення вбудованих Plugin - застарілі метадані маніфесту env-var для provider/channel - застарілі hook і псевдоніми типів Plugin provider, поки provider переходять на - явні hook для catalog, auth, thinking, replay і transport + явні hook каталогу, auth, thinking, replay і transport - застарілі псевдоніми середовища виконання, такі як `api.runtime.taskFlow`, - `api.runtime.subagent.getSession`, `api.runtime.stt` і застарілі + `api.runtime.subagent.getSession`, `api.runtime.stt`, а також застарілі `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` -- застарілу розділену реєстрацію memory-plugin, поки memory plugins переходять на +- застаріла розділена реєстрація memory-plugin, поки memory plugin переходять на `registerMemoryCapability` -- застарілі helper SDK channel для нативних схем повідомлень, керування згадками, - форматування вхідних envelope і вкладення можливостей схвалення -- застарілі псевдоніми route key channel і helper для comparable-target, поки плагіни переходять - на `openclaw/plugin-sdk/channel-route` -- activation hints, які замінюються володінням внеском маніфесту -- резервний шлях середовища виконання `setup-api`, поки дескриптори setup переходять до холодних - метаданих `setup.requiresRuntime: false` -- hook provider `discovery`, поки hook каталогу provider переходять до +- застарілі допоміжні засоби SDK channel для нативних схем повідомлень, шлюзування згадок, + форматування вхідного envelope і вкладеності можливостей погодження +- застарілі псевдоніми ключів маршруту channel і допоміжних засобів comparable-target, поки Plugin + переходять на `openclaw/plugin-sdk/channel-route` +- підказки активації, які замінюються власністю внеску маніфесту +- резервний шлях середовища виконання `setup-api`, поки дескриптори setup переходять на холодні + метадані `setup.requiresRuntime: false` +- hook `discovery` provider, поки hook каталогу provider переходять на `catalog.run(...)` -- метадані channel `showConfigured` / `showInSetup`, поки пакети channel переходять - до `openclaw.channel.exposure` -- застарілі ключі config політик середовища виконання, поки doctor мігрує операторів до +- метадані `showConfigured` / `showInSetup` channel, поки пакети channel переходять + на `openclaw.channel.exposure` +- застарілі ключі config політики середовища виконання, поки doctor мігрує операторів на `agentRuntime` -- резервний шлях метаданих config згенерованих вбудованих channel, поки впроваджуються - метадані `channelConfigs` на основі registry-first -- прапори env для вимкнення збереженого реєстру Plugin та міграції встановлення, поки - потоки repair переводять операторів на `openclaw plugins registry --refresh` і +- резервний шлях для згенерованих метаданих config вбудованих channel, поки впроваджуються + метадані `channelConfigs` з пріоритетом реєстру +- змінні середовища для вимкнення збереженого реєстру Plugin і міграції встановлення, поки + потоки виправлення мігрують операторів на `openclaw plugins registry --refresh` і `openclaw doctor --fix` - застарілі шляхи config для web search, web fetch і x_search, що належать Plugin, поки doctor мігрує їх до `plugins.entries..config` -- застарілі авторські config `plugins.installs` і псевдоніми шляхів завантаження вбудованих Plugin, поки - метадані встановлення переміщуються до керованого станом реєстру Plugin +- застарілий створений конфігурацією `plugins.installs` і псевдоніми шляху завантаження вбудованих Plugin, + поки метадані встановлення переміщуються до журналу Plugin, яким керує стан -Новий код Plugin має надавати перевагу заміні, вказаній у реєстрі та в конкретному посібнику з міграції. Наявні плагіни можуть і далі використовувати шлях сумісності, доки документація, діагностика та примітки до релізу не оголосять вікно видалення. +Новий код Plugin має надавати перевагу заміні, зазначеній у реєстрі та в +конкретному посібнику з міграції. Наявні Plugin можуть і далі використовувати +шлях сумісності, доки документація, діагностика та примітки до релізу не +оголосять вікно видалення. ## Примітки до релізу -Примітки до релізу мають включати майбутні застарівання Plugin із цільовими датами та посиланнями на документацію з міграції. Це попередження має з’явитися до того, як шлях сумісності перейде в `removal-pending` або `removed`. +Примітки до релізу мають включати майбутні застарівання Plugin із цільовими +датами та посиланнями на документацію міграції. Таке попередження має +з’явитися до того, як шлях сумісності перейде до `removal-pending` або `removed`. diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 75baea839..8a34ecf5c 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,53 @@ --- read_when: - - Ви створюєте плагін OpenClaw - - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна + - Ви створюєте Plugin для OpenClaw + - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації) -title: маніфест Plugin +title: Маніфест Plugin x-i18n: - generated_at: "2026-04-28T01:41:58Z" + generated_at: "2026-04-28T02:07:55Z" model: gpt-5.4 provider: openai - source_hash: f19c39220215b72341b89540ee952642c3387effb8f32cbc5a623571e4f9afd1 + source_hash: 8610826b5c7b27a3dab2abb498c3506905a48680450f0c22cf08f91e76c0b62b source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **рідного маніфесту Plugin OpenClaw**. +Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**. -Сумісні компонування пакетів описано тут: [Пакети Plugin](/uk/plugins/bundles). +Сумісні макети пакетів описано в [Пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфесту: - Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude - без маніфесту +- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту - Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію -за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені -кореневі каталоги Skills, кореневі каталоги команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude і підтримувані набори хуків, коли компонування відповідає -очікуванням рантайму OpenClaw. +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skill, корені команд Claude, значення за замовчуванням із `settings.json` для пакета Claude, значення LSP за замовчуванням для пакета Claude та підтримувані набори hook, якщо макет відповідає очікуванням середовища виконання OpenClaw. -Кожен рідний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у -**кореневому каталозі Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються -помилками Plugin і блокують валідацію конфігурації. +Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. -Повний посібник із системи Plugin дивіться тут: [Plugins](/uk/tools/plugin). -Про рідну модель можливостей і актуальні вказівки щодо зовнішньої сумісності: +Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin). +Щодо власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності див.: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого -Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску рантайму -Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску середовища виконання Plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок UI для конфігурації -- метаданих автентифікації, онбордингу й налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- ідентифікації Plugin, валідації конфігурації та підказок інтерфейсу для конфігурації +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища постачальника, варіанти автентифікації) - підказок активації для поверхонь control-plane -- скороченого володіння сімейством моделей +- скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих запуску QA, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для каналу, об’єднаних у каталог і поверхні валідації +- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- метаданих конфігурації, специфічних для каналу, що об’єднуються в каталозі та поверхнях валідації -**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення -точок входу коду або метаданих встановлення npm. Для цього призначені код вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення точок входу коду або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -121,19 +110,19 @@ Plugin. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Ключ API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Ключ API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Ключ API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -152,74 +141,76 @@ Plugin. ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Щоб залишити Plugin вимкненим за замовчуванням, не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легкого модуля виявлення провайдера, відносний до кореневого каталогу Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного рантайму Plugin. | -| `modelSupport` | Ні | `object` | Метадані скороченого запису для сімейств моделей, що належать маніфесту і використовуються для автоматичного завантаження Plugin до рантайму. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього read-only переліку, онбордингу, засобів вибору моделей, аліасів і придушення без завантаження рантайму Plugin. | -| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, якою володіє провайдер. Використовуйте її, щоб виключити локальні/self-hosted провайдери з віддалених каталогів цін або зіставити посилання на провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | -| `modelIdNormalization` | Ні | `object` | Очищення аліасів/префіксів ідентифікаторів моделей, яким володіє провайдер і яке має виконуватися до завантаження рантайму провайдера. | -| `providerEndpoints` | Ні | `object[]` | Метадані хоста/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження рантайму провайдера. | -| `providerRequest` | Ні | `object` | Легкі метадані сімейства провайдерів і сумісності запитів, які використовуються загальною політикою запитів до завантаження рантайму провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких хук синтетичної автентифікації, що належить Plugin, має перевірятися під час cold discovery моделей до завантаження рантайму. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, якими володіє вбудований Plugin і які представляють не секретний локальний стан, OAuth або ambient credential. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/стану провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час перехідного періоду депрекейту. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує базовий API key провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого підключення прапорців CLI. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що ініціюється провайдерами, командами, каналами, маршрутами та можливостями. Лише метадані; фактичною поведінкою все одно володіє рантайм Plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму Plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори запуску QA, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. | -| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого компонента для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту і об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореневого каталогу Plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори постачальників, які повинні автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори постачальників, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до полегшеного модуля виявлення постачальника, відносний до кореня Plugin, для метаданих каталогу постачальників у межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску середовища виконання. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для постачальників, якими володіє цей Plugin. Це контракт control-plane для майбутнього режиму читання списків, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | +| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, що належить постачальнику. Використовуйте її, щоб виключити локальних/self-hosted постачальників із віддалених каталогів цін або зіставити посилання постачальника з ідентифікаторами каталогів OpenRouter/LiteLLM без жорстко закодованих ідентифікаторів постачальників у ядрі. | +| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів ідентифікаторів моделей, що належить постачальнику та має виконуватись до завантаження середовища виконання постачальника. | +| `providerEndpoints` | Ні | `object[]` | Метадані хоста/baseUrl кінцевих точок, що належать маніфесту, для маршрутів постачальника, які ядро має класифікувати до завантаження середовища виконання постачальника. | +| `providerRequest` | Ні | `object` | Легкі метадані сімейства постачальника та сумісності запитів, які використовуються загальною політикою запитів до завантаження середовища виконання постачальника. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів висновку CLI, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на постачальників або бекенди CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження середовища виконання. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають надавати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані змінних середовища для пошуку автентифікації/стану постачальника. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час перехідного періоду депрецяції. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори постачальників, які повинні повторно використовувати інший ідентифікатор постачальника для пошуку автентифікації, наприклад постачальник для кодування, який спільно використовує базовий ключ API постачальника та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу на основі env або поверхонь автентифікації, які мають бачити загальні допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного постачальника та простого прив’язування прапорців CLI. | +| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, яке запускається постачальником, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою все ще володіє середовище виконання Plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх hook автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі значення за замовчуванням для розуміння медіа для ідентифікаторів постачальників, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту та об’єднуються в поверхнях виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | +| `name` | Ні | `string` | Зручна для людини назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Підписи інтерфейсу, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження рантайму провайдера. -Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти налаштування, -похідні від дескрипторів, і метадані каталогу встановлення без завантаження рантайму провайдера. +OpenClaw зчитує це до завантаження середовища виконання постачальника. +Списки налаштування постачальника використовують ці варіанти маніфесту, варіанти +налаштування, отримані з дескриптора, і метадані каталогу встановлення без +завантаження середовища виконання постачальника. -| Поле | Обов’язкове | Тип | Що воно означає | -| -------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та CLI-потоках. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних засобах вибору, керованих асистентом. | -| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору асистента, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають переспрямовувати користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор постачальника, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід маршрутизувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та потоках CLI. | +| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все одно дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Ім’я прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, за замовчуванням це `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть -помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду рантайму Plugin. +Використовуйте `commandAliases`, коли Plugin володіє ім’ям команди під час +виконання, яке користувачі можуть помилково додати в `plugins.allow` або +спробувати запустити як кореневу команду CLI. OpenClaw використовує ці +метадані для діагностики без імпорту коду середовища виконання Plugin. ```json { @@ -233,37 +224,40 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | +| `name` | Так | `string` | Ім’я команди, що належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо така існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane -мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли Plugin може з мінімальними витратами +оголосити, які події control-plane мають включати його в план активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку рантайму, не замінює `register(...)` і не гарантує, що код -Plugin уже було виконано. Планувальник активації використовує ці поля, щоб -звузити набір кандидатів Plugin перед поверненням до наявних метаданих володіння маніфесту, таких як -`providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не +реєструє поведінку під час виконання, не замінює `register(...)` і не +гарантує, що код Plugin уже виконано. Планувальник активації використовує ці +поля, щоб звузити коло кандидатів Plugin, перш ніж перейти до наявних +метаданих володіння в маніфесті, таких як `providers`, `channels`, +`commandAliases`, `setup.providers`, `contracts.tools` і hooks. -Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових -підказок планувальника, які не можна подати через ці поля володіння. -Використовуйте верхньорівневий `cliBackends` для аліасів runtime CLI, таких як `claude-cli`, -`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для -вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. +Віддавайте перевагу найвужчим метаданим, які вже описують володіння. +Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup +або `contracts`, якщо ці поля виражають зв’язок. Використовуйте `activation` +для додаткових підказок планувальника, які неможливо подати через ці поля +володіння. +Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища +виконання CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; +`activation.onAgentHarnesses` призначений лише для вбудованих ідентифікаторів +agent harness, які ще не мають поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку рантайму та не -замінює `register(...)`, `setupEntry` або інші точки входу runtime/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має -змінювати коректність, доки все ще існують застарілі fallback-варіанти володіння маніфестом. +Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і +не замінює `register(...)`, `setupEntry` або інші точки входу runtime/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим +завантаженням Plugin, тому відсутність метаданих активації зазвичай впливає +лише на продуктивність; це не повинно змінювати коректність, поки ще існують +застарілі резервні механізми володіння з маніфесту. ```json { @@ -278,43 +272,46 @@ Plugin уже було виконано. Планувальник активац } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих harness агента, які мають включати цей Plugin до планів активації/завантаження. Для аліасів backend CLI використовуйте верхньорівневий `cliBackends`. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Відносні до кореня шляхи конфігурації, які мають включати цей Plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control-plane. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори постачальників, які мають включати цей Plugin у плани активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих agent harness, які мають включати цей Plugin у плани активації/завантаження. Для псевдонімів бекенду CLI використовуйте верхньорівневий `cliBackends`. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin у плани активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin у плани активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Відносні до кореня шляхи конфігурації, які мають включати цей Plugin у плани запуску/завантаження, коли шлях присутній і явно не вимкнений. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються плануванням активації control-plane. За можливості віддавайте перевагу вужчим полям. | -Поточні споживачі в продакшені: +Поточні активні споживачі: -- планування CLI, що запускається командою, повертається до застарілих - `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harness і верхньорівневий `cliBackends[]` для аліасів runtime CLI -- планування setup/каналу, що запускається каналом, повертається до застарілого володіння `channels[]`, - коли явні метадані активації каналу відсутні -- планування Plugin під час запуску використовує `activation.onConfigPaths` для некональних кореневих - поверхонь конфігурації, таких як блок `browser` у вбудованому Plugin браузера -- планування setup/runtime, що запускається провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні - метадані активації провайдера відсутні +- планування CLI, що запускається командою, використовує резервний механізм + через застарілі `commandAliases[].cliCommand` або `commandAliases[].name` +- планування запуску agent-runtime використовує `activation.onAgentHarnesses` + для вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів + середовища виконання CLI +- планування setup/каналу, що запускається каналом, використовує резервний + механізм через застаріле володіння `channels[]`, коли явні метадані активації + каналу відсутні +- планування Plugin під час запуску використовує `activation.onConfigPaths` + для некальних поверхонь кореневої конфігурації, таких як блок `browser` + вбудованого Plugin браузера +- планування setup/runtime, що запускається постачальником, використовує + резервний механізм через застарілі `providers[]` і верхньорівневе володіння + `cliBackends[]`, коли явні метадані активації постачальника відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback -володіння маніфестом. Наприклад, `activation-command-hint` означає, що -спрацювало `activation.onCommands`, а `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста і тестів; авторам Plugin слід і надалі оголошувати метадані, -які найкраще описують володіння. +Діагностика планувальника може відрізняти явні підказки активації від +резервного володіння з маніфесту. Наприклад, `activation-command-hint` +означає, що збіглося `activation.onCommands`, а `manifest-command-alias` +означає, що планувальник натомість використав володіння `commandAliases`. +Ці мітки причин призначені для діагностики хоста й тестів; авторам Plugin слід +і надалі оголошувати ті метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runners під -спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною -реєстрацією CLI все одно володіє рантайм Plugin через легку поверхню -`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner +під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими й статичними; +фактичною реєстрацією CLI все одно володіє середовище виконання Plugin через +полегшену поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -330,12 +327,12 @@ Plugin уже було виконано. Планувальник активац | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | -------- | ------------------------------------------------------------------- | | `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані Plugin -до завантаження рантайму. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні +легкі метадані, що належать Plugin, до завантаження середовища виконання. ```json { @@ -354,61 +351,66 @@ Plugin уже було виконано. Планувальник активац } ``` -Верхньорівневий `cliBackends` залишається валідним і надалі описує -backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, -для потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається чинним і надалі описує бекенди +висновку CLI. `setup.cliBackends` — це поверхня дескриптора, специфічна для +setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо `setup.providers` і `setup.cliBackends` присутні, вони є бажаною -поверхнею пошуку setup на основі дескрипторів. Якщо дескриптор лише -звужує кандидатний Plugin, а для setup усе ще потрібні багатші runtime-хуки часу налаштування, -встановіть `requiresRuntime: true` і залиште `setup-api` як -резервний шлях виконання. +Якщо присутні, `setup.providers` і `setup.cliBackends` є рекомендованою +поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор +лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших hook +середовища виконання на етапі налаштування, установіть `requiresRuntime: true` +і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та -env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності -під час перехідного періоду депрекейту, але небудовані Plugin, які досі його використовують, -отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для -setup/status у `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` у загальні механізми пошуку +автентифікації постачальника та змінних середовища. `providerAuthEnvVars` +залишається підтримуваним через адаптер сумісності протягом перехідного +періоду депрецяції, але не вбудовані Plugin, які все ще його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані змінних +середовища для setup/стану в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, +OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` -вказує, що runtime setup не потрібен. Явні записи `providerAuthChoices` і надалі є -бажаними для власних міток, прапорців CLI, області онбордингу та метаданих асистента. +оголшує, що runtime setup не потрібен. Явні записи `providerAuthChoices` +і надалі є пріоритетними для власних підписів, прапорців CLI, області +онбордингу та метаданих помічника. -Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin, що працює лише на дескрипторах, усе ж постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й надалі його ігнорує. Якщо -`requiresRuntime` не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали -дескриптори без цього прапорця, не ламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів +достатньо для поверхні setup. OpenClaw трактує явне значення `false` як +контракт лише на дескриптори й не виконуватиме `setup-api` або +`openclaw.setupEntry` для пошуку setup. Якщо Plugin, що працює лише через +дескриптори, усе ж постачає один із цих записів runtime setup, OpenClaw +повідомляє про додаткову діагностику й надалі ігнорує його. Пропущений +`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugin, +які додали дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, який належить Plugin, -нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними -серед усіх виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою, а не вибором -переможця на основі порядку виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають +залишатися унікальними серед виявлених Plugin. Неоднозначне володіння +завершується безпечним відхиленням, а не вибором переможця за порядком +виявлення. -Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, -якщо `setup-api` реєструє провайдера або backend CLI, які не оголошені -в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. -Ця діагностика є додатковою і не відхиляє застарілі Plugin. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про +розходження дескрипторів, якщо `setup-api` реєструє постачальника або бекенд +CLI, не оголошений у дескрипторах маніфесту, або якщо для дескриптора немає +відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють +застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, який показується під час setup або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження рантайму Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор постачальника, що надається під час setup або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які підтримує цей постачальник без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/стану можуть перевіряти до завантаження runtime Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, які показуються під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, які використовуються для пошуку setup спочатку за дескрипторами. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup постачальників, що надаються під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів часу setup, що використовуються для пошуку setup за принципом descriptor-first. Нормалізовані ідентифікатори мають бути глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup після пошуку за дескриптором усе ще потребує виконання `setup-api`. | ## Довідник `uiHints` @@ -427,21 +429,21 @@ OpenClaw повідомляє додаткову діагностику й на } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | ----------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Підпис поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги інтерфейсу. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -зчитувати без імпорту рантайму Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння +можливостями, які OpenClaw може зчитувати без імпорту runtime Plugin. ```json { @@ -465,47 +467,49 @@ OpenClaw повідомляє додаткову діагностику й на Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ---------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------------ | | `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий хук профілю зовнішньої автентифікації належить цьому Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів ембедингів пам’яті, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin, для перевірок контрактів вбудованих компонентів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори постачальників, hook зовнішнього профілю автентифікації яких належить цьому Plugin. | +| `speechProviders` | `string[]` | Ідентифікатори постачальників мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори постачальників транскрипції в реальному часі, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори постачальників голосу в реальному часі, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори постачальників ембедингів пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори постачальників розуміння медіа, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори постачальників генерації зображень, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори постачальників генерації відео, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори постачальників web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори постачальників вебпошуку, якими володіє цей Plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори постачальників імпорту, якими володіє цей Plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви agent tool, якими володіє цей Plugin для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для фабрик розширень -лише для вбудованого app-server Codex. Вбудовані трансформації результатів інструментів мають -оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть -реєструвати middleware результатів інструментів, оскільки цей стик може переписувати вивід -інструментів високої довіри до того, як його побачить модель. +`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик +розширень лише для app-server Codex. Вбудовані перетворення результатів +інструментів мають оголошувати `contracts.agentToolResultMiddleware` і +реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні +Plugin не можуть реєструвати middleware результатів інструментів, оскільки +цей шов може переписувати високодовірений вивід інструментів до того, як його +побачить модель. -Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий fallback сумісності, але він повільніший і -буде видалений після завершення міграційного вікна. +Plugin постачальників, які реалізують `resolveExternalAuthProfiles`, мають +оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення +все ще працюють через застарілий резервний механізм сумісності, але він +повільніший і буде видалений після завершення вікна міграції. -Вбудовані провайдери ембедингів пам’яті мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з -вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише Plugin-власник до того, як повний рантайм Gateway зареєструє -провайдерів. +Вбудовані постачальники ембедингів пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який +вони надають, зокрема для вбудованих адаптерів, таких як `local`. Автономні +шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише +Plugin-власник до того, як повне runtime Gateway зареєструє постачальників. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має -типові моделі, пріоритет fallback автоматичної автентифікації або нативну підтримку документів, які -загальним допоміжним засобам ядра потрібні до завантаження рантайму. Ключі також мають бути оголошені в -`contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли постачальник +розуміння медіа має моделі за замовчуванням, пріоритет резервної автоматичної +автентифікації або нативну підтримку документів, які потрібні загальним +допоміжним засобам ядра до завантаження runtime. Ключі також мають бути +оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -528,43 +532,46 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP } ``` -Кожен запис провайдера може містити: +Кожен запис постачальника може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові значення відповідності можливість-модель, які використовуються, коли в конфігурації не вказано модель. | -| `autoPriority` | `Record` | Менші числа сортуються вище для автоматичного fallback провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей постачальник. | +| `defaultModels` | `Record` | Значення за замовчуванням для відповідності можливість-модель, що використовуються, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору постачальника на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує постачальник. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до -завантаження рантайму. Read-only виявлення setup/status каналу може використовувати ці метадані -безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або -коли `setup.requiresRuntime: false` вказує, що runtime setup не потрібен. +Використовуйте `channelConfigs`, коли канальному Plugin потрібні легкі +метадані конфігурації до завантаження runtime. Виявлення setup/стану каналу в +режимі лише читання може напряму використовувати ці метадані для налаштованих +зовнішніх каналів, коли запис setup недоступний або коли +`setup.requiresRuntime: false` оголошує, що runtime setup не потрібен. -`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ -конфігурації користувача. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. -OpenClaw зчитує метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим -каналом, до виконання коду рантайму Plugin. +`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий +розділ конфігурації користувача. Користувачі, як і раніше, налаштовують +екземпляри каналів у `channels.`. OpenClaw зчитує метадані +маніфесту, щоб визначити, якому Plugin належить налаштований канал, до +виконання коду runtime Plugin. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні -шляхи: +Для канального Plugin `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` валідує `plugins.entries..config` - `channelConfigs..schema` валідує `channels.` -Небудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але поверхні -схеми конфігурації cold-path, setup і Control UI не можуть знати форму параметрів, -які належать каналу, доки не виконається рантайм Plugin. +Не вбудовані Plugin, які оголошують `channels[]`, також мають оголошувати +відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити +Plugin, але схеми конфігурації холодного шляху, setup і поверхні Control UI +не знатимуть форму параметрів, що належать каналу, доки не виконається +runtime Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, -які виконуються до завантаження рантайму каналу. Вбудовані канали також можуть публікувати -ті самі типові значення через `package.json#openclaw.channel.commands` разом з іншими -метаданими каталогу каналу, що належать пакету. +`nativeSkillsAutoEnabled` можуть оголошувати статичні значення `auto` за +замовчуванням для перевірок конфігурації команд, які виконуються до +завантаження runtime каналу. Вбудовані канали також можуть публікувати ті самі +значення за замовчуванням через `package.json#openclaw.channel.commands` +разом з іншими метаданими каталогу каналів, що належать їхньому пакету. ```json { @@ -597,21 +604,22 @@ OpenClaw зчитує метадані маніфесту, щоб визначи Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, яка об’єднується з поверхнями вибору та перегляду, коли метадані рантайму ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | -| `commands` | `object` | Статичні auto-типові значення native command і native skill для перевірок конфігурації до рантайму. | -| `preferOver` | `string[]` | Застарілі або менш пріоритетні ідентифікатори Plugin, які цей канал має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові підписи інтерфейсу/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, що об’єднується в поверхнях вибору та перевірки, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | +| `commands` | `object` | Статичні auto-значення за замовчуванням для native command і native skill для перевірок конфігурації до runtime. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | -### Заміна іншого Plugin каналу +### Заміна іншого канального Plugin -Використовуйте `preferOver`, коли ваш Plugin є бажаним власником ідентифікатора каналу, який -також може надавати інший Plugin. Типові випадки: перейменований ідентифікатор Plugin, окремий -Plugin, який замінює вбудований Plugin, або підтримуваний fork, який зберігає той самий -ідентифікатор каналу для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для +ідентифікатора каналу, який також може надавати інший Plugin. Типові випадки — +це перейменований ідентифікатор Plugin, окремий Plugin, що замінює вбудований +Plugin, або підтримуваний форк, який зберігає той самий ідентифікатор каналу +для сумісності конфігурації. ```json { @@ -632,21 +640,24 @@ Plugin, який замінює вбудований Plugin, або підтри } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор каналу, і -бажаний ідентифікатор Plugin. Якщо менш пріоритетний Plugin було вибрано лише тому, -що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній -конфігурації рантайму, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача -все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw -зберігає цей вибір і повідомляє діагностику дубльованого каналу/інструменту, а не -тихо змінює запитаний набір Plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та +бажаний ідентифікатор Plugin. Якщо менш пріоритетний Plugin було вибрано лише +тому, що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його +в ефективній конфігурації runtime, щоб одним каналом і його інструментами +володів один Plugin. Явний вибір користувача все одно має перевагу: якщо +користувач явно вмикає обидва Plugin, OpenClaw зберігає цей вибір і повідомляє +про діагностику дубльованих каналів/інструментів замість того, щоб мовчки +змінювати запитаний набір Plugin. -Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той +самий канал. Це не загальне поле пріоритету, і воно не перейменовує ключі +конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з -скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження рантайму Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin +постачальника зі скорочених ідентифікаторів моделей на кшталт `gpt-5.5` або +`claude-sonnet-4.6` до завантаження runtime Plugin. ```json { @@ -659,26 +670,28 @@ Plugin, який замінює вбудований Plugin, або підтри OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє Plugin +- явні посилання `provider/model` використовують метадані маніфесту `providers`, + що належать власнику - `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований - Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера +- якщо збігаються один не вбудований Plugin і один вбудований Plugin, перемагає + не вбудований Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не + вкажуть постачальника Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | -------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження рантайму Plugin. Це джерело, яким володіє маніфест, для фіксованих -рядків каталогу, аліасів провайдерів, правил придушення та режиму виявлення. Оновлення в runtime -і далі належить коду рантайму провайдера, але маніфест повідомляє ядру, коли рантайм -потрібен. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей +постачальника до завантаження runtime Plugin. Це джерело маніфесту для +фіксованих рядків каталогу, псевдонімів постачальників, правил приглушення та +режиму виявлення. Оновлення runtime все ще належить коду runtime постачальника, +але маніфест повідомляє ядру, коли runtime потрібен. ```json { @@ -729,74 +742,83 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають бути вказані у верхньорівневому `providers`. | -| `aliases` | `Record` | Аліаси провайдерів, які мають резолвитися до провайдера-власника для планування каталогу або придушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin придушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або чи він потребує runtime. | +| Поле | Тип | Що воно означає | +| -------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів постачальників, якими володіє цей Plugin. Ключі також мають з’являтися у верхньорівневому `providers`. | +| `aliases` | `Record` | Псевдоніми постачальників, які мають розв’язуватися у постачальника-власника для планування каталогу або приглушення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для постачальника. | +| `discovery` | `Record` | Чи можна читати каталог постачальника з метаданих маніфесту, оновлювати його в кеш або чи він потребує runtime. | -`aliases` бере участь у пошуку володіння провайдером для планування model-catalog. -Цілі аліасів мають бути верхньорівневими провайдерами, якими володіє той самий Plugin. Коли -список, відфільтрований за провайдером, використовує аліас, OpenClaw може прочитати маніфест-власник і -застосувати перевизначення API/base URL аліаса без завантаження рантайму провайдера. +`aliases` бере участь у пошуку власника постачальника для планування +каталогу моделей. Цілі псевдонімів мають бути верхньорівневими +постачальниками, якими володіє той самий Plugin. Коли список, відфільтрований +за постачальником, використовує псевдонім, OpenClaw може зчитати маніфест +власника й застосувати перевизначення API/base URL псевдоніма без завантаження +runtime постачальника. -`suppressions` замінює старий хук runtime провайдера `suppressBuiltInModel`. -Записи придушення враховуються лише тоді, коли провайдер належить Plugin або -оголошений як ключ `modelCatalog.aliases`, який вказує на провайдера-власника. Runtime-хуки -придушення більше не викликаються під час резолвингу моделей. +`suppressions` замінює старий hook runtime постачальника +`uppressBuiltInModel`. Записи приглушення враховуються лише тоді, коли +постачальник належить Plugin або оголошений як ключ `modelCatalog.aliases`, +що вказує на постачальника-власника. Hooks приглушення runtime більше не +викликаються під час розв’язання моделей. -Поля провайдера: +Поля постачальника: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------ | -| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | ------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язковий base URL за замовчуванням для моделей у каталозі цього постачальника. | +| `api` | `ModelApi` | Необов’язковий адаптер API за замовчуванням для моделей у каталозі цього постачальника. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до каталогу цього постачальника. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що воно означає | -| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Нативне context window провайдера. | -| `contextTokens` | `number` | Необов’язкова ефективна runtime-межа контексту, якщо вона відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | +| Поле | Тип | Що воно означає | +| --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `id` | `string` | Локальний для постачальника ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API на рівні моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення base URL на рівні моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки на рівні моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Нативне вікно контексту постачальника. | +| `contextTokens` | `number` | Необов’язкова ефективна межа контексту runtime, якщо вона відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язковий `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте придушення лише тоді, коли рядок взагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується для недоступного статусу. | -| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Ідентифікатор локальної для провайдера моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок взагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується для статусу, відмінного від available. | +| `replaces` | `string[]` | Старі локальні для постачальника ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для постачальника ідентифікатор моделі-замінника для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | -Поля придушення: +Поля приглушення: -| Поле | Тип | Що воно означає | -| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який треба придушити. Має належати цьому Plugin або бути оголошеним як аліас-власник. | -| `model` | `string` | Локальний для провайдера ідентифікатор моделі, яку треба придушити. | -| `reason` | `string` | Необов’язкове повідомлення, яке показується, коли придушений рядок запитується напряму. | -| `when.baseUrlHosts` | `string[]` | Необов’язковий список хостів ефективного base URL провайдера, які мають збігтися, перш ніж придушення буде застосовано. | -| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації провайдера, які мають збігтися, перш ніж придушення буде застосовано. | +| Поле | Тип | Що воно означає | +| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | +| `provider` | `string` | Ідентифікатор постачальника для рядка вищого джерела, який слід приглушити. Має належати цьому Plugin або бути оголошеним як псевдонім-власник. | +| `model` | `string` | Локальний для постачальника ідентифікатор моделі, яку слід приглушити. | +| `reason` | `string` | Необов’язкове повідомлення, що показується, коли приглушений рядок запитується напряму. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список хостів ефективного provider base URL, які мають бути наявні, перш ніж застосовується приглушення. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації постачальника, які мають бути наявні, перш ніж застосовується приглушення. | -Не розміщуйте в `modelCatalog` дані, які існують лише в runtime. Якщо провайдеру потрібен стан -облікового запису, API-запит або виявлення локального процесу, щоб визначити повний набір моделей, -оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані лише для runtime. Використовуйте `static` +лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списків і +засобів вибору, відфільтрованих за постачальником, могли пропустити виявлення +реєстру/runtime. Використовуйте `refreshable`, коли рядки маніфесту є +корисними початковими або додатковими записами списку, але оновлення/кеш +можуть пізніше додати більше рядків; самі по собі рядки `refreshable` не є +авторитетними. Використовуйте `runtime`, коли OpenClaw мусить завантажити +runtime постачальника, щоб дізнатися список. ## Довідник `modelIdNormalization` -Використовуйте `modelIdNormalization` для легкого очищення ідентифікаторів моделей, яким володіє провайдер і яке має -відбуватися до завантаження рантайму провайдера. Це дозволяє зберігати аліаси, такі як короткі назви -моделей, застарілі локальні ідентифікатори провайдера та правила префіксів проксі, у маніфесті -Plugin-власника, а не в таблицях вибору моделей ядра. +Використовуйте `modelIdNormalization` для легкого очищення ідентифікаторів +моделей, що належить постачальнику і має відбуватися до завантаження runtime +постачальника. Це дозволяє зберігати псевдоніми, як-от короткі назви моделей, +застарілі локальні ідентифікатори постачальника та правила префіксів проксі, у +маніфесті Plugin-власника, а не в таблицях вибору моделей ядра. ```json { @@ -816,37 +838,40 @@ Plugin-власника, а не в таблицях вибору моделей } ``` -Поля провайдера: +Поля постачальника: -| Поле | Тип | Що воно означає | -| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- | -| `aliases` | `Record` | Точні аліаси ідентифікаторів моделей без урахування регістру. Значення повертаються в тому вигляді, як записані. | -| `stripPrefixes` | `string[]` | Префікси, які слід видалити перед пошуком аліаса; корисно для застарілого дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який додається, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксів для bare-id після пошуку аліаса з ключами `modelPrefix` і `prefix`. | +| Поле | Тип | Що воно означає | +| ------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------ | +| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються так, як записані. | +| `stripPrefixes` | `string[]` | Префікси, які слід видаляти перед пошуком псевдонімів; корисно для застарілого дублювання provider/model. | +| `prefixWhenBare` | `string` | Префікс, який слід додавати, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксації для bare-id після пошуку псевдонімів, ключами є `modelPrefix` і `prefix`. | ## Довідник `providerEndpoints` -Використовуйте `providerEndpoints` для класифікації кінцевих точок, яку загальна політика запитів -має знати до завантаження рантайму провайдера. Ядро, як і раніше, володіє значенням кожного -`endpointClass`; маніфести Plugin володіють метаданими хоста та base URL. +Використовуйте `providerEndpoints` для класифікації кінцевих точок, про яку +загальна політика запитів має знати до завантаження runtime постачальника. +Ядро, як і раніше, володіє значенням кожного `endpointClass`; маніфести Plugin +володіють метаданими хоста та base URL. Поля кінцевої точки: -| Поле | Тип | Що воно означає | -| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | | `endpointClass` | `string` | Відомий ядру клас кінцевої точки, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом кінцевої точки. | -| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом кінцевої точки. Додайте префікс `.` для зіставлення лише за суфіксом домену. | -| `baseUrls` | `string[]` | Точні нормалізовані HTTP(S) base URL, які зіставляються з класом кінцевої точки. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який слід видалити зі збіжних хостів, щоб отримати префікс регіону Google Vertex. | +| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом кінцевої точки. | +| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом кінцевої точки. Додавайте префікс `.` для зіставлення лише суфіксів домену. | +| `baseUrls` | `string[]` | Точні нормалізовані HTTP(S) base URL, які зіставляються з класом кінцевої точки. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який слід прибрати з відповідних хостів, щоб отримати префікс регіону Google Vertex. | ## Довідник `providerRequest` -Використовуйте `providerRequest` для легких метаданих сумісності запитів, які загальній -політиці запитів потрібні без завантаження рантайму провайдера. Переписування payload, специфічне для -поведінки, залишайте в runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів. +Використовуйте `providerRequest` для легких метаданих сумісності запитів, +які потрібні загальній політиці запитів без завантаження runtime +постачальника. Переписування payload, специфічне для поведінки, залишайте в +hooks runtime постачальника або в спільних допоміжних засобах сімейства +постачальників. ```json { @@ -864,19 +889,19 @@ Plugin-власника, а не в таблицях вибору моделей } ``` -Поля провайдера: +Поля постачальника: -| Поле | Тип | Що воно означає | -| --------------------- | ------------ | --------------------------------------------------------------------------------------- | -| `family` | `string` | Мітка сімейства провайдерів, яка використовується для загальних рішень і діагностики сумісності запитів. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства провайдерів для спільних допоміжних засобів запитів. | -| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI; наразі це `supportsStreamingUsage`. | +| Поле | Тип | Що воно означає | +| --------------------- | ------------ | ---------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства постачальника, що використовується загальними рішеннями сумісності запитів і діагностикою. | +| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства постачальника для спільних допоміжних засобів запитів. | +| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | ## Довідник `modelPricing` -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до -завантаження рантайму. Кеш ціноутворення Gateway зчитує ці метадані без імпорту коду -рантайму провайдера. +Використовуйте `modelPricing`, коли постачальнику потрібна поведінка control-plane +для ціноутворення до завантаження runtime. Кеш ціноутворення Gateway зчитує ці +метадані без імпорту коду runtime постачальника. ```json { @@ -897,140 +922,149 @@ Plugin-власника, а не в таблицях вибору моделей } ``` -Поля провайдера: +Поля постачальника: -| Поле | Тип | Що воно означає | -| ------------ | ----------------- | --------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | Встановіть `false` для локальних/self-hosted провайдерів, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Відображення пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Відображення пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| Поле | Тип | Що воно означає | +| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/self-hosted постачальників, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Зіставлення пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього постачальника. | +| `liteLLM` | `false \| object` | Зіставлення пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього постачальника. | Поля джерела: -| Поле | Тип | Що воно означає | -| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера у зовнішньому каталозі, якщо він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей, що містять слеш, як вкладені посилання provider/model; корисно для проксі-провайдерів, таких як OpenRouter. | -| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей у зовнішньому каталозі. `version-dots` пробує версійні ідентифікатори з крапками, такі як `claude-opus-4.6`. | +| Поле | Тип | Що воно означає | +| -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор постачальника зовнішнього каталогу, якщо він відрізняється від ідентифікатора постачальника OpenClaw, наприклад `z-ai` для постачальника `zai`. | +| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей, що містять слеш, як вкладені посилання provider/model; корисно для проксі-постачальників, таких як OpenRouter. | +| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує версії з крапками, як-от `claude-opus-4.6`. | -### Індекс провайдерів OpenClaw +### Індекс постачальників OpenClaw -Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, -Plugin яких, можливо, ще не встановлено. Він не є частиною маніфесту Plugin. -Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — це -внутрішній fallback-контракт, який у майбутньому використовуватимуть поверхні -встановлюваних провайдерів і вибору моделей до встановлення, коли Plugin провайдера не встановлено. +Індекс постачальників OpenClaw — це preview-метадані, якими володіє OpenClaw, +для постачальників, Plugin яких іще можуть бути не встановлені. Він не є +частиною маніфесту Plugin. Маніфести Plugin залишаються авторитетним джерелом +для встановлених Plugin. Індекс постачальників є внутрішнім резервним +контрактом, який використовуватимуть майбутні поверхні постачальників, що +можуть встановлюватися, і засоби вибору моделей до встановлення, коли Plugin +постачальника не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. 2. `modelCatalog` маніфесту встановленого Plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Preview-рядки індексу провайдерів OpenClaw. +4. Preview-рядки індексу постачальників OpenClaw. -Індекс провайдерів не повинен містити секрети, стан увімкнення, runtime-хуки або -актуальні дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися -стабільними метаданими відображення, якщо лише поля runtime-адаптера, такі як `api`, -`baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими -з маніфестом встановленого Plugin. Провайдери з живим виявленням `/models` мають -записувати оновлені рядки через явний шлях кешу каталогу моделей замість -того, щоб під час звичайного переліку або онбордингу викликати API провайдера. +Індекс постачальників не повинен містити секрети, стан увімкнення, hooks +runtime або актуальні дані моделей, специфічні для облікового запису. Його +preview-каталоги використовують ту саму форму рядка постачальника `modelCatalog`, +що й маніфести Plugin, але мають обмежуватися стабільними метаданими +відображення, якщо тільки поля runtime-адаптера, як-от `api`, `baseUrl`, +ціни або прапорці сумісності, не підтримуються навмисно синхронізованими з +маніфестом встановленого Plugin. Постачальники з виявленням через живий +`/models` мають записувати оновлені рядки через явний шлях кешу каталогу +моделей замість того, щоб змушувати звичайний список або онбординг викликати +API постачальника. -Записи індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, -чий Plugin було винесено з ядра або який інакше ще не встановлено. Ці -метадані повторюють шаблон каталогу каналів: назви пакета, специфікації npm install, -очікувана цілісність і легкі мітки варіантів автентифікації достатні, щоб показати -встановлюваний варіант setup. Після встановлення Plugin його маніфест має перевагу, і -запис індексу провайдера для цього провайдера ігнорується. +Записи індексу постачальників також можуть містити метадані Plugin, що +встановлюється, для постачальників, Plugin яких було винесено з ядра або які +інакше ще не встановлені. Ці метадані віддзеркалюють шаблон каталогу каналів: +назви пакета, специфікації встановлення npm, очікуваної цілісності та легких +міток варіантів автентифікації достатньо, щоб показати варіант setup, який +можна встановити. Після встановлення Plugin його маніфест отримує пріоритет, +а запис індексу постачальників для цього постачальника ігнорується. -Застарілі верхньорівневі ключі можливостей є deprecated. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне -завантаження маніфесту більше не трактує ці верхньорівневі поля як -володіння можливостями. +Застарілі верхньорівневі ключі можливостей депрецовано. Використовуйте +`openclaw doctor --fix`, щоб перенести `speechProviders`, +`realtimeTranscriptionProviders`, `realtimeVoiceProviders`, +`mediaUnderstandingProviders`, `imageGenerationProviders`, +`videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` у +`contracts`; звичайне завантаження маніфесту більше не розглядає ці +верхньорівневі поля як володіння можливостями. -## Маніфест і `package.json` +## Маніфест і package.json -Ці два файли виконують різні ролі: +Ці два файли мають різні призначення: -| Файл | Для чого використовувати | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, gating встановлення, setup або метаданих каталогу | +| Файл | Використовуйте для | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок інтерфейсу, які мають існувати до запуску коду Plugin | +| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, що використовується для точок входу, контролю встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте таке правило: - якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки npm install, розміщуйте це в `package.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля `package.json`, що впливають на виявлення -Деякі метадані Plugin до рантайму навмисно розміщуються в `package.json` у блоці +Деякі метадані Plugin до runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує точки входу рідного Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу рантайму JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Легка точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення стану каналу/SecretRef. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу setup JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, аліаси та текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані auto-типових значень native command і native skill, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження рантайму каналу. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| `openclaw.extensions` | Оголошує точки входу власних Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує точку входу built JavaScript setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легкі метадані каталогу каналів, як-от підписи, шляхи до документації, псевдоніми та текст для поверхонь вибору. | +| `openclaw.channel.commands` | Статичні метадані auto-значень за замовчуванням для native command і native skill, що використовуються поверхнями конфігурації, аудиту та списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є хоч якийсь вхід у систему?» без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях установлення, коли доступно кілька джерел установлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із нижньою межею semver на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного канального Plugin під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в -онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти постачальника/каналу/setup +з’являються під час онбордингу до завантаження runtime. `package.json#openclaw.install` +повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач +вибирає один із цих варіантів. Не переносіть підказки встановлення в +`openclaw.plugin.json`. `openclaw.install.minHostVersion` застосовується під час встановлення та -завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають -Plugin на старіших хостах. +завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але +валідні значення пропускають Plugin на старіших хостах. Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно завершувалися помилкою, -якщо отриманий артефакт npm більше не відповідає закріпленому релізу. -Інтерактивний онбординг усе ще пропонує довірені специфікації npm реєстру, включно з -простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, із невідповідністю назви пакета та -невалідні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` присутнє, але немає валідного джерела npm, яке воно може закріпити. -Коли `expectedIntegrity` присутнє, -потоки встановлення/оновлення застосовують його; коли його пропущено, резолвинг реєстру -записується без закріплення цілісності. +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього +каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки +оновлення завершувалися безпечною відмовою, якщо отриманий артефакт npm більше +не відповідає закріпленому релізу. Інтерактивний онбординг і далі пропонує +довірені специфікації npm із реєстру, зокрема просто назви пакетів і dist-tag, +для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені +цілісністю, без цілісності, з невідповідністю імені пакета та з недійсним +джерелом default-choice. Вона також попереджає, коли `expectedIntegrity` +наявний, але немає валідного джерела npm, яке можна ним закріпити. Коли +`expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; +коли його пропущено, розв’язання через реєстр записується без закріплення +цілісності. -Plugin каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів -або сканування SecretRef потрібно визначати налаштовані облікові записи без завантаження повного -рантайму. Запис setup має надавати метадані каналу разом із безпечною для setup конфігурацією, -статусом і адаптерами секретів; мережеві клієнти, слухачі gateway і -transport runtimes слід залишати в основній точці входу розширення. +Канальні Plugin мають надавати `openclaw.setupEntry`, коли статус, список +каналів або сканування SecretRef мають ідентифікувати налаштовані облікові +записи без завантаження повного runtime. Запис setup має надавати метадані +каналу разом з безпечними для setup адаптерами конфігурації, статусу та +секретів; мережеві клієнти, слухачі gateway і transport runtime слід +залишати в основній точці входу розширення. -Поля точки входу runtime не перевизначають перевірки меж пакета для полів -точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити -завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля точок входу runtime не перевизначають перевірки меж пакета для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може +зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно обмежене. Воно не -робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення -відновлюватися після конкретних застарілих збоїв оновлення вбудованих Plugin, таких як -відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого -вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить +довільно зламані конфігурації придатними для встановлення. Наразі він лише +дозволяє потокам встановлення відновлюватися після певних застарілих збоїв +оновлення вбудованих Plugin, таких як відсутній шлях до вбудованого Plugin або +застарілий запис `channels.` для того самого вбудованого Plugin. Помилки +конфігурації, не пов’язані з цим, усе одно блокують установлення та скеровують +операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля -перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного +модуля перевірки: ```json { @@ -1046,14 +1080,16 @@ transport runtimes слід залишати в основній точці вх } ``` -Використовуйте це, коли потокам setup, doctor, status або read-only перевірки присутності потрібна дешева -перевірка автентифікації так/ні до завантаження повного Plugin каналу. Збережений стан автентифікації — -це не налаштований стан каналу: не використовуйте ці метадані для автоувімкнення Plugin, -відновлення залежностей runtime або вирішення, чи має завантажуватися рантайм каналу. -Цільовий експорт має бути невеликою функцією, яка зчитує лише збережений стан; не -спрямовуйте його через повний barrel рантайму каналу. +Використовуйте це, коли потокам setup, doctor, status або виявлення presence у +режимі лише читання потрібна легка перевірка автентифікації типу так/ні до +завантаження повного канального Plugin. Збережений стан автентифікації не є +налаштованим станом каналу: не використовуйте ці метадані для автоматичного +вмикання Plugin, відновлення залежностей runtime або для вирішення, чи слід +завантажувати runtime каналу. Цільовий експорт має бути невеликою функцією, +яка зчитує лише збережений стан; не маршрутизуйте його через повний barrel +runtime каналу. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +`openclaw.channel.configuredState` має ту саму форму для легких перевірок налаштованого стану лише через env: ```json @@ -1070,57 +1106,58 @@ transport runtimes слід залишати в основній точці вх } ``` -Використовуйте це, коли канал може визначити налаштований стан на основі env або інших невеликих -нерuntime-входів. Якщо для перевірки потрібне повне резолвлення конфігурації або справжній -рантайм каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповідати щодо налаштованого стану за env +або іншими невеликими вхідними даними, не пов’язаними з runtime. Якщо перевірка +потребує повного розв’язання конфігурації або реального runtime каналу, +залишайте цю логіку в hook `config.hasConfiguredState` Plugin. ## Пріоритет виявлення (дубльовані ідентифікатори Plugin) -OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, шляхи, явно вибрані конфігурацією). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поряд із ним. +OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобально встановлені, робочий простір, шляхи, явно вибрані в конфігурації). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. Пріоритет, від найвищого до найнижчого: 1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` 2. **Вбудований** — Plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugin, виявлені відносно поточного workspace +3. **Глобально встановлений** — Plugin, встановлені в глобальний корінь Plugin OpenClaw +4. **Робочий простір** — Plugin, виявлені відносно поточного робочого простору Наслідки: -- Fork або застаріла копія вбудованого Plugin у workspace не затьмарить вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace. +- Форк або застаріла копія вбудованого Plugin у робочому просторі не зможе затінити вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. - Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не в runtime. +- **Кожен Plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима, наприклад `{ "type": "object", "additionalProperties": false }`. +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошено - маніфестом Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. -- Якщо Plugin встановлено, але його маніфест або схема зламані чи відсутні, + повинні посилатися на **такі ідентифікатори Plugin, які можна виявити**. + Невідомі ідентифікатори є **помилками**. +- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і - у Doctor + логах з’являється **попередження**. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація + зберігається, а в Doctor і журналах з’являється **попередження**. -Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). +Повну схему `plugins.*` див. у [Довідник конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест є **обов’язковим для рідних Plugin OpenClaw**, включно з локальними завантаженнями з файлової системи. Runtime і далі завантажує модуль Plugin окремо; маніфест призначений лише для виявлення + валідації. -- Рідні маніфести розбираються як JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані env vars (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші read-only поверхні все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. -- Метадані runtime wizard, які потребують коду провайдера, див. у [Runtime-хуках провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime і далі завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення + валідації. +- Власні маніфести аналізуються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо фінальне значення все ще є об’єктом. +- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте власних верхньорівневих ключів. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо вони не потрібні Plugin. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу постачальника або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). +- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані runtime wizard, що потребують коду постачальника, див. у [Хуки runtime постачальника](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів, наприклад pnpm `allow-build-scripts` + `pnpm rebuild `. ## Пов’язане diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 95e003400..a3cfe1e60 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,330 +1,332 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту Plugin + - Вибір правильного підшляху plugin-sdk для імпорту плагіна - Аудит підшляхів bundled-plugin і допоміжних поверхонь summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-28T01:47:22Z" + generated_at: "2026-04-28T02:07:53Z" model: gpt-5.4 provider: openai - source_hash: 67de782db5ef5a60ffe104ba67749590e70acb31f615e8c6e5049f688a3c2422 + source_hash: c56a83c4cf89a40286328bd58079af21a1f5fcf2392c5f6a1e08f873c65e49d6 source_path: plugins/sdk-subpaths.md workflow: 15 --- Plugin SDK представлено як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований + На цій сторінці наведено каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталлю - реалізації, якщо лише сторінка документації не просуває їх явно. + зарезервовані допоміжні підшляхи bundled-plugin також наведено там, але вони є деталями + реалізації, якщо тільки окрема сторінка документації явно не рекомендує їх. - Посібник з розробки Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Посібник зі створення плагінів дивіться в [Огляд Plugin SDK](/uk/plugins/sdk-overview). - ## Точка входу Plugin + ## Вхід плагіна - | Subpath | Ключові експорти | - | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin; для нових тестів розширень віддавайте перевагу вузькоспрямованим тестовим підшляхам | - | `plugin-sdk/plugin-test-api` | Мінімальний конструктор моків `OpenClawPluginApi` для прямих модульних тестів реєстрації Plugin | - | `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестування життєвого циклу облікових записів Channel, каталогів, send-config, моків runtime, hooks і загального контракту Channel | - | `plugin-sdk/channel-target-testing` | Спільний набір тестів для випадків помилок під час визначення цілі Channel | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби для контрактів реєстрації Plugin, маніфесту пакета, публічного артефакту, runtime API, побічних ефектів імпорту та прямого імпорту | - | `plugin-sdk/plugin-test-runtime` | Фікстури runtime Plugin, реєстру, реєстрації provider, майстра налаштування та TaskFlow runtime для тестів | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби для контрактів runtime provider, auth, discovery, onboard, catalog, web-search/fetch і майстра | - | `plugin-sdk/test-env` | Фікстури тестового середовища, fetch/network, live-test, тимчасової файлової системи та керування часом | - | `plugin-sdk/test-fixtures` | Загальні тестові фікстури для CLI, sandbox, Skills, agent-message, system-event, terminal, chunking, auth-token і typed-case | - | `plugin-sdk/migration` | Допоміжні засоби для елементів provider міграції, наприклад `createMigrationItem`, константи причин, маркери статусу елементів, засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби runtime міграції, наприклад `copyMigrationFileItem` і `writeMigrationReport` | + | Підшлях | Основні експорти | + | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів плагінів; для нових тестів розширень віддавайте перевагу цільовим тестовим підшляхам | + | `plugin-sdk/plugin-test-api` | Мінімальний побудовник моку `OpenClawPluginApi` для модульних тестів прямої реєстрації плагінів | + | `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестів життєвого циклу облікових записів каналу, каталогів, конфігурації надсилання, моку runtime, hook і загального контракту каналу | + | `plugin-sdk/channel-target-testing` | Спільний набір тестів для випадків помилок під час визначення цілі каналу | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби для контрактів реєстрації плагіна, маніфесту пакета, публічного артефакту, runtime API, побічних ефектів імпорту та прямого імпорту | + | `plugin-sdk/plugin-test-runtime` | Фікстури для тестів runtime плагіна, реєстру, реєстрації провайдера, майстра налаштування та runtime TaskFlow | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби для контрактів runtime провайдера, автентифікації, виявлення, онбордингу, каталогу, мультимедійних можливостей, web-search/fetch і майстра | + | `plugin-sdk/provider-http-test-mocks` | Опціональні моки HTTP/автентифікації Vitest для тестів провайдера, які використовують `plugin-sdk/provider-http` | + | `plugin-sdk/test-env` | Фікстури середовища тестування, fetch/мережі, live-тестів, тимчасової файлової системи та керування часом | + | `plugin-sdk/test-fixtures` | Загальні тестові фікстури CLI, sandbox, skill, повідомлень агента, системних подій, термінала, chunking, токенів автентифікації та типізованих випадків | + | `plugin-sdk/migration` | Допоміжні засоби для елементів провайдера міграції, такі як `createMigrationItem`, константи причин, маркери статусу елементів, засоби редагування та `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні засоби для runtime міграції, такі як `copyMigrationFileItem` і `writeMigrationReport` | - - | Subpath | Ключові експорти | + + | Підшлях | Основні експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Експорт кореневої схеми Zod для `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби для майстра налаштування, prompt allowlist, побудовники статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, побудовники статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації та action-gate з кількома обліковими записами, а також для fallback облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби для нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби для пошуку облікового запису та fallback за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів і дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації/гейтів дій багатьох облікових записів і резервного використання облікового запису за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного використання облікового запису за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації Channel і універсальний конструктор | - | `plugin-sdk/bundled-channel-config-schema` | Схеми конфігурації Channel для bundled OpenClaw лише для підтримуваних bundled Plugin | - | `plugin-sdk/channel-config-schema-legacy` | Застарілий псевдонім сумісності для bundled-схем конфігурації Channel | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби для нормалізації/валідації користувацьких команд Telegram із fallback на bundled-контракт | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби для gate авторизації команд | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та загальний побудовник | + | `plugin-sdk/bundled-channel-config-schema` | Схеми конфігурації каналів bundled OpenClaw лише для підтримуваних bundled-плагінів | + | `plugin-sdk/channel-config-schema-legacy` | Застарілий псевдонім сумісності для bundled-схем конфігурації каналів | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним bundled-контрактом | + | `plugin-sdk/command-gating` | Вузькі допоміжні засоби для шлюзування авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби для життєвого циклу/фіналізації draft stream | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для маршрутизації inbound і побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби для запису inbound і dispatch | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення чернеткових потоків | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для побудови вхідних маршрутів і envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби для запису та диспетчеризації вхідних даних | | `plugin-sdk/messaging-targets` | Допоміжні засоби для розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби для завантаження outbound media | - | `plugin-sdk/outbound-send-deps` | Легковаговий пошук залежностей outbound send для адаптерів Channel | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби runtime для outbound delivery, identity, send delegate, session, formatting і планування payload | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби для нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби для життєвого циклу thread-binding і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа agent | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки conversation/thread, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб для знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби runtime для визначення group-policy | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби для знімків/зведень стану Channel | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації Channel | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації Channel | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin для Channel | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби для читання/редагування конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби для визначення доступу до груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби для семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel сумісності для debounce inbound, зіставлення згадок, допоміжних засобів mention-policy та envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби для debounce inbound | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби для форматування inbound envelope | - | `plugin-sdk/channel-location` | Допоміжні засоби для контексту Channel location і форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування Channel для відкинутих inbound і збоїв typing/ack | - | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби для message-action у Channel, а також застарілі допоміжні засоби для native schema, збережені для сумісності Plugin | - | `plugin-sdk/channel-route` | Спільні допоміжні засоби для нормалізації route, визначення цілей на основі parser, перетворення thread-id у рядок, ключів route для dedupe/compact, типів parsed-target і порівняння route/target | - | `plugin-sdk/channel-targets` | Допоміжні засоби розбору цілей; виклики порівняння route мають використовувати `plugin-sdk/channel-route` | - | `plugin-sdk/channel-contract` | Типи контракту Channel | + | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей вихідного надсилання для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної доставки, ідентичності, делегата надсилання, сесії, форматування та планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник мультимедійного payload агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби для binding розмов/потоків, pairing та налаштованих binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагіна каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби автентифікації/захисту direct-DM | + | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних даних, зіставлення згадок, допоміжних засобів політики згадок і envelope | + | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних даних | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні runtime вхідних даних | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідного envelope | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту та форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для відкидання вхідних даних і збоїв typing/ack | + | `plugin-sdk/channel-send-result` | Типи результатів відповідей | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності плагінів | + | `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації маршрутів, визначення цілей на основі парсера, перетворення thread-id у рядок, dedupe/compact ключів маршрутів, типів parsed-target і порівняння маршрутів/цілей | + | `plugin-sdk/channel-targets` | Допоміжні засоби розбору цілей; виклики порівняння маршрутів мають використовувати `plugin-sdk/channel-route` | + | `plugin-sdk/channel-contract` | Типи контрактів каналів | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту secret, зокрема `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-контрактів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret-цілей | - - | Subpath | Ключові експорти | + + | Підшлях | Основні експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад provider LM Studio для налаштування, виявлення каталогу та підготовки моделей runtime | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних типових параметрів сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | - | `plugin-sdk/provider-setup` | Добірні допоміжні засоби налаштування локальних/self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Цілеспрямовані допоміжні засоби налаштування self-hosted provider, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові параметри бекенду CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime для визначення API-key для provider Plugin | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-key, наприклад `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату auth OAuth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider Plugin | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для auth provider | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей у runtime | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних серверних значень за замовчуванням, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Значення за замовчуванням для бекенду CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для плагінів провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключа/запису профілю, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth-автентифікації | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби кінцевих точок provider і допоміжні засоби нормалізації model-id, наприклад `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Hook runtime для розширення каталогу provider і seams реєстру provider Plugin для контрактних тестів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик replay, допоміжні засоби endpoint провайдерів і нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Hook runtime для розширення каталогу провайдерів і seams реєстру plugin-provider для контрактних тестів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей кінцевих точок provider, помилки HTTP provider і допоміжні засоби multipart form для транскрибування аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, наприклад `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider, яким не потрібне підключення enable Plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, наприклад `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime provider web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби сумісності xAI, наприклад `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера, HTTP-помилки провайдера та допоміжні засоби multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення плагіна | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, а також scoped-сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби native transport provider, зокрема guarded fetch, перетворення transport message і потоки подій transport із можливістю запису | - | `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби нативного транспорту провайдера, такі як guarded fetch, трансформації transport message і доступні для запису потоки transport event | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчингу конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | `plugin-sdk/group-activation` | Вузькі допоміжні засоби для режиму активації груп і розбору команд | + | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації групи та розбору команд | - - | Subpath | Ключові експорти | + + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, наприклад `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби для визначення approver і auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери native можливостей/доставки approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб для визначення Gateway approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні засоби завантаження адаптера native approval для гарячих точок входу Channel | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для handler approval; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native target approval + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді approval для exec/plugin | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload approval для exec/plugin, допоміжні засоби маршрутизації/runtime native approval і допоміжні засоби структурованого відображення approval, наприклад `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби для скидання дедуплікації inbound reply | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту Channel без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Native auth команд, форматування меню динамічних аргументів і допоміжні засоби native session-target | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | + | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у межах того самого чату | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки нативного approval | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження адаптера нативного approval handler для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для approval handler; віддавайте перевагу вужчим seams адаптера/gateway, якщо їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілі нативного approval + binding облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді exec/plugin approval | + | `plugin-sdk/approval-runtime` | Допоміжні засоби payload exec/plugin approval, допоміжні засоби маршрутизації/runtime нативного approval і допоміжні засоби структурованого відображення approval, такі як `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання dedupe для вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів Channel | + | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні засоби command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь secret Channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби для trust, DM gating, external-content, редагування чутливого тексту, порівняння secret у сталий час і збирання secret | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-контрактів для поверхонь секретів каналів/плагінів | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-контрактів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилки SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher, fetch із захистом від SSRF, помилка SSRF і допоміжні засоби політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру тіла запиту/timeout | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру тіла запиту/тайм-ауту | - | Subpath | Ключові експорти | + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби для runtime/logging/backup/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби для env runtime, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових параметрів, розбору URL CDP і допоміжних засобів auth browser-control | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби для реєстрації та пошуку runtime-context Channel | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення плагінів | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/значень за замовчуванням, розбору URL CDP і допоміжних засобів автентифікації browser-control | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби для команд/hooks/http/interactive Plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби для pipeline Webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби для lazy-імпорту/прив’язки runtime, наприклад `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби для виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби для форматування CLI, очікування, версій, виклику аргументів і lazy-груп команд | - | `plugin-sdk/gateway-runtime` | Клієнт Gateway, CLI RPC Gateway, помилки протоколу Gateway і допоміжні засоби виправлення channel-status | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів конфігурації Plugin, зокрема `OpenClawConfig` і типів конфігурації channel/provider | - | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби runtime для пошуку конфігурації Plugin, наприклад `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, наприклад `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби для знімків конфігурації поточного процесу, наприклад `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setters тестових знімків | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби для нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли bundled-поверхня контракту Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel `text-runtime` | - | `plugin-sdk/approval-runtime` | Допоміжні засоби approval для exec/plugin, конструктори можливостей approval, допоміжні засоби auth/profile, допоміжні засоби native routing/runtime і форматування шляху структурованого відображення approval | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, Heartbeat, планувальник reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби для dispatch/finalize reply і міток conversation | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби для reply-history у короткому вікні та маркери, наприклад `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive плагіна | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy імпорту/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і lazy command-group | + | `plugin-sdk/gateway-runtime` | Клієнт Gateway, CLI RPC Gateway, помилки протоколу Gateway і допоміжні засоби patch стану каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації плагінів, таких як `OpenClawConfig`, і типів конфігурації каналів/провайдерів | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації плагіна в runtime, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і сетери тестового знімка | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли bundled-поверхня контракту Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel text-runtime | + | `plugin-sdk/approval-runtime` | Допоміжні засоби approval exec/plugin, побудовники можливостей approval, допоміжні засоби auth/profile, допоміжні засоби нативної маршрутизації/runtime і форматування шляхів структурованого відображення approval | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime вхідних даних/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і міток розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби та маркери історії відповідей короткого вікна, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби для chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби для шляху сховища сесій, ключа сесії, updated-at і мутацій сховища | - | `plugin-sdk/cron-store-runtime` | Допоміжні засоби для шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні засоби для шляхів каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби для route/session-key/прив’язки облікового запису, наприклад `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби для зведень стану channel/account, типових станів runtime-state і метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби для визначення цілей | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби для нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із входів, подібних до fetch/request | - | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool | - | `plugin-sdk/tool-send` | Витягування канонічних полів цілі send з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби для шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби для logger підсистем і редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби для режимів і перетворення таблиць Markdown | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби для перевизначення model/session, наприклад `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби для визначення конфігурації provider Talk | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби для читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби для реентерабельного блокування файлів | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби для кешу дедуплікації на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch | - | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації agent runtime | - | `plugin-sdk/boolean-param` | Зчитувач параметрів boolean із м’яким приведенням | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби для визначення збігів небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби для bootstrap пристрою і токенів pair | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів для passive-channel, статусу й ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби для команди `/models` і відповіді provider | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби для переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби для реєстру/build/serialize native команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики tool для плану runtime, класифікація результатів terminal, допоміжні засоби для форматування/деталізації прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби для виявлення кінцевих точок Z.AI | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутації сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів стану/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/binding облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, значень стану runtime за замовчуванням і метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витягування рядкових URL із входів на кшталт fetch/request | + | `plugin-sdk/run-command` | Виконавець команд із тайм-лімітом і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk-провайдера | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/file-lock` | Повторно вхідні допоміжні засоби file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe з дисковою підтримкою | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесії ACP і dispatch відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Визначення binding ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | + | `plugin-sdk/boolean-param` | Читач параметрів логічних значень із м’яким приведенням | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби виведення списку команд skill | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби bridge tool OpenClaw, допоміжні засоби політики tool плану runtime, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | - | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності Channel | - | `plugin-sdk/concurrency-runtime` | Допоміжний засіб для обмеженої конкурентності async-завдань | - | `plugin-sdk/dedupe-runtime` | Допоміжні засоби для кешу дедуплікації в пам’яті | - | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб для очищення черги очікуваної outbound-доставки | - | `plugin-sdk/file-access-runtime` | Допоміжні засоби для безпечних шляхів локальних файлів і джерел медіа | - | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби для подій і видимості Heartbeat | + | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | + | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності async-задач | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу dedupe в пам’яті | + | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб спорожнення черги очікуваної вихідної доставки | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів до локальних файлів і джерел медіа | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | | `plugin-sdk/number-runtime` | Допоміжний засіб числового приведення | - | `plugin-sdk/secure-random-runtime` | Допоміжні засоби для безпечних токенів/UUID | - | `plugin-sdk/system-event-runtime` | Допоміжні засоби для черги system event | - | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності transport | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище вузькоспрямовані підшляхи runtime | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби для обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби для діагностичних прапорців, подій і trace-context | - | `plugin-sdk/error-runtime` | Допоміжні засоби для графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби для обгорнутого fetch, proxy і pinned lookup | - | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Зчитувач тіла відповіді з обмеженням без широкої поверхні media runtime | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації configured binding або сховищ pairing | + | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | + | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | + | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи runtime | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context | + | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/runtime-fetch` | runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Читач обмеженого тіла відповіді без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан binding розмови без маршрутизації налаштованого binding або сховищ pairing | | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту і фільтрація додаткового контексту без широких імпортів config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби для приведення й нормалізації primitive record/string без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Допоміжні засоби для нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби для конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби для каталогу/ідентичності/робочого простору agent | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту й фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних записів/рядків без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і хостів SCP | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів із підтримкою конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Subpath | Ключові експорти | + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби для fetch/transform/store медіа, а також конструктори payload медіа | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, наприклад `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби для failover генерації медіа, вибору кандидатів і повідомлень про відсутні моделі | - | `plugin-sdk/media-understanding` | Типи provider для розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтованих на provider | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для text/markdown/logging, наприклад видалення тексту, видимого для assistant, допоміжні засоби для рендерингу/chunking/таблиць markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб для chunking вихідного тексту | - | `plugin-sdk/speech` | Типи provider мовлення, а також експорти допоміжних засобів директив, реєстру, валідації, конструктора TTS, сумісного з OpenAI, і мовлення, орієнтованих на provider | - | `plugin-sdk/speech-core` | Спільні типи provider мовлення, а також експорти допоміжних засобів реєстру, директив, нормалізації та мовлення | - | `plugin-sdk/realtime-transcription` | Типи provider для транскрибування в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи provider голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи provider генерації зображень, а також допоміжні засоби для image asset/data URL | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи provider/request/result генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошуку provider і розбору model-ref | - | `plugin-sdk/video-generation` | Типи provider/request/result генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошуку provider і розбору model-ref | - | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення route | - | `plugin-sdk/webhook-path` | Допоміжні засоби для нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби для завантаження віддалених/локальних медіа | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники media payload | + | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтованих на провайдерів | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення видимого асистенту тексту, допоміжні засоби рендерингу/chunking/таблиць Markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдерів мовлення, а також експорти директив, реєстру, валідації, сумісного з OpenAI побудовника TTS і допоміжних засобів мовлення, орієнтованих на провайдерів | + | `plugin-sdk/speech-core` | Спільні експорти типів провайдерів мовлення, реєстру, директив, нормалізації та допоміжних засобів мовлення | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень, а також допоміжні засоби ресурсів зображень/data URL | + | `plugin-sdk/image-generation-core` | Спільні допоміжні засоби типів, failover, auth і реєстру генерації зображень | + | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільні допоміжні засоби типів, failover, пошуку провайдера та розбору model-ref для генерації музики | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні допоміжні засоби типів, failover, пошуку провайдера та розбору model-ref для генерації відео | + | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin. Нові тести розширень мають імпортувати натомість вузькоспрямовані підшляхи SDK, наприклад `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для прямих модульних тестів реєстрації Plugin без імпорту мостів допоміжних засобів тестування репозиторію | - | `plugin-sdk/channel-test-helpers` | Допоміжні засоби тестування, орієнтовані на Channel, для загальних контрактів actions/setup/status, перевірок каталогів, життєвого циклу запуску облікових записів, потоків send-config, моків runtime, проблем статусу, вихідної доставки та реєстрації hooks | - | `plugin-sdk/channel-target-testing` | Спільний набір перевірок випадків помилок під час визначення цілей для тестів Channel | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів для пакетів Plugin, реєстрації, публічних артефактів, прямого імпорту, runtime API та побічних ефектів імпорту | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів для runtime, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream provider | - | `plugin-sdk/test-fixtures` | Загальні фікстури для захоплення runtime CLI, контексту sandbox, записувача Skills, agent-message, system-event, terminal-text, chunking, auth-token і typed-case | + | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів плагінів. Нові тести розширень мають натомість імпортувати сфокусовані підшляхи SDK, такі як `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для модульних тестів прямої реєстрації плагінів без імпорту bridge допоміжних засобів тестування репозиторію | + | `plugin-sdk/channel-test-helpers` | Допоміжні засоби тестування, орієнтовані на канали, для загальних контрактів дій/налаштування/стану, перевірок каталогів, життєвого циклу запуску облікового запису, thread-ing конфігурації надсилання, моків runtime, проблем стану, вихідної доставки та реєстрації hook | + | `plugin-sdk/channel-target-testing` | Спільний набір перевірок випадків помилок визначення цілі для тестів каналів | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів пакета плагіна, реєстрації, публічного артефакту, прямого імпорту, runtime API та побічних ефектів імпорту | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime провайдера, auth, discovery, onboard, каталогу, майстра, мультимедійних можливостей, web-search/fetch і stream | + | `plugin-sdk/provider-http-test-mocks` | Опціональні моки HTTP/auth для Vitest для тестів провайдера, які використовують `plugin-sdk/provider-http` | + | `plugin-sdk/test-fixtures` | Загальні фікстури захоплення runtime CLI, контексту sandbox, writer для Skills, повідомлень агента, системних подій, тексту термінала, chunking, auth-token і типізованих випадків | - | Subpath | Ключові експорти | + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helpers | | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embeddings хоста пам’яті, доступ до реєстру, локальний provider і загальні допоміжні засоби для batch/remote | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і загальні batch/remote helper-и | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби базового runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для допоміжних засобів базового runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю | + | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого Markdown для плагінів, суміжних із пам’яттю | | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - | Family | Поточні підшляхи | Призначення | + | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser Plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | - | Допоміжні засоби, специфічні для Channel | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі seams сумісності/допоміжних засобів bundled Channel. Нові Plugin мають імпортувати загальні підшляхи SDK або локальні barrel Plugin. | - | Допоміжні засоби, специфічні для auth/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams допоміжних засобів bundled-функцій/Plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі seams сумісності/допоміжних засобів bundled channel. Нові плагіни мають імпортувати загальні підшляхи SDK або локальні barrel-и плагіна. | + | Допоміжні засоби, специфічні для auth/плагінів | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні seams bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | -## Пов’язане +## Пов’язані матеріали - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення плагінів](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/sdk-testing.md b/docs/uk/plugins/sdk-testing.md index 6dfcc6d90..43c5cd4a9 100644 --- a/docs/uk/plugins/sdk-testing.md +++ b/docs/uk/plugins/sdk-testing.md @@ -1,49 +1,52 @@ --- read_when: - - Ви пишете тести для плагіна - - Вам потрібні утиліти тестування з SDK плагіна - - Ви хочете зрозуміти контрактні тести для bundled плагінів + - Ви пишете тести для Plugin + - Вам потрібні утиліти тестування з SDK Plugin + - Ви хочете зрозуміти контрактні тести для вбудованих плагінів sidebarTitle: Testing summary: Утиліти та шаблони тестування для плагінів OpenClaw title: Тестування Plugin x-i18n: - generated_at: "2026-04-28T01:19:19Z" + generated_at: "2026-04-28T02:07:58Z" model: gpt-5.4 provider: openai - source_hash: dcc9f0340a651ab742150101ceb78b65ea450b90720bc06e96bb19535db3d83d + source_hash: 264c652d0a857a4e5b570d177011b04318757d30c5169bbcf432c038e6b8b7d5 source_path: plugins/sdk-testing.md workflow: 15 --- -Довідник з утиліт тестування, шаблонів і примусового застосування lint для плагінів OpenClaw. +Довідник з утиліт тестування, шаблонів і lint-контролю для плагінів OpenClaw. - **Шукаєте приклади тестів?** Посібники how-to містять готові приклади тестів: + **Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів: [Тести плагінів каналів](/uk/plugins/sdk-channel-plugins#step-6-test) і [Тести плагінів провайдерів](/uk/plugins/sdk-provider-plugins#step-6-test). ## Утиліти тестування -**Імпорт мока API плагіна:** `openclaw/plugin-sdk/plugin-test-api` +**Імпорт мока API Plugin:** `openclaw/plugin-sdk/plugin-test-api` -**Імпорт контракту каналу:** `openclaw/plugin-sdk/channel-contract-testing` +**Імпорт контрактів каналів:** `openclaw/plugin-sdk/channel-contract-testing` -**Імпорт допоміжних засобів тестування каналу:** `openclaw/plugin-sdk/channel-test-helpers` +**Імпорт допоміжних засобів тестування каналів:** `openclaw/plugin-sdk/channel-test-helpers` **Імпорт тестування цілей каналу:** `openclaw/plugin-sdk/channel-target-testing` -**Імпорт контракту плагіна:** `openclaw/plugin-sdk/plugin-test-contracts` +**Імпорт контрактів Plugin:** `openclaw/plugin-sdk/plugin-test-contracts` -**Імпорт тестування runtime плагіна:** `openclaw/plugin-sdk/plugin-test-runtime` +**Імпорт тестування середовища виконання Plugin:** `openclaw/plugin-sdk/plugin-test-runtime` -**Імпорт контракту провайдера:** `openclaw/plugin-sdk/provider-test-contracts` +**Імпорт контрактів провайдерів:** `openclaw/plugin-sdk/provider-test-contracts` + +**Імпорт HTTP-моків провайдерів:** `openclaw/plugin-sdk/provider-http-test-mocks` **Імпорт тестування середовища/мережі:** `openclaw/plugin-sdk/test-env` **Імпорт загальних фікстур:** `openclaw/plugin-sdk/test-fixtures` -Для нових тестів плагінів надавайте перевагу наведеним нижче цільовим підшляхам. Широкий barrel `openclaw/plugin-sdk/testing` призначений лише для сумісності зі застарілим кодом. +Для нових тестів плагінів віддавайте перевагу наведеним нижче спеціалізованим підшляхам. Широкий +barrel `openclaw/plugin-sdk/testing` підтримується лише для сумісності зі застарілим кодом. ```typescript import { @@ -57,71 +60,77 @@ import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-help import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts"; import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime"; import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts"; +import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks"; import { withEnv, withFetchPreconnect } from "openclaw/plugin-sdk/test-env"; import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fixtures"; ``` -### Доступні експортовані елементи +### Доступні експорти | Export | Призначення | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `createTestPluginApi` | Створює мінімальний мок API плагіна для прямих unit-тестів реєстрації. Імпортуйте з `plugin-sdk/plugin-test-api` | -| `expectChannelInboundContextContract` | Перевіряє форму вхідного контексту каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | -| `installChannelOutboundPayloadContractSuite` | Встановлює набір випадків контракту вихідного payload каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | -| `createStartAccountContext` | Створює контексти життєвого циклу облікового запису каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `installChannelActionsContractSuite` | Встановлює загальний набір випадків контракту дій повідомлень каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `installChannelSetupContractSuite` | Встановлює загальний набір випадків контракту налаштування каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `installChannelStatusContractSuite` | Встановлює загальний набір випадків контракту статусу каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `expectDirectoryIds` | Перевіряє id каталогів із функції списку каталогів. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `describePluginRegistrationContract` | Встановлює перевірки контракту реєстрації плагіна. Імпортуйте з `plugin-sdk/plugin-test-contracts` | -| `registerSingleProviderPlugin` | Реєструє один плагін провайдера у smoke-тестах завантажувача. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `registerProviderPlugin` | Захоплює всі типи провайдерів з одного плагіна. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `registerProviderPlugins` | Захоплює реєстрації провайдерів у кількох плагінах. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `requireRegisteredProvider` | Перевіряє, що колекція провайдерів містить id. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `createRuntimeEnv` | Створює змокане середовище runtime CLI/плагіна. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `createPluginSetupWizardStatus` | Створює допоміжні засоби статусу майстра налаштування для плагінів каналів. Імпортуйте з `plugin-sdk/plugin-test-runtime` | -| `describeOpenAIProviderRuntimeContract` | Встановлює перевірки контракту runtime для сімейства провайдерів. Імпортуйте з `plugin-sdk/provider-test-contracts` | -| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок розв’язання цілі. Імпортуйте з `plugin-sdk/channel-target-testing` | -| `shouldAckReaction` | Перевіряє, чи має канал додати реакцію-підтвердження. Імпортуйте з `plugin-sdk/channel-feedback` | -| `removeAckReactionAfterReply` | Видаляє реакцію-підтвердження після доставки відповіді. Імпортуйте з `plugin-sdk/channel-feedback` | -| `createTestRegistry` | Створює фікстуру реєстру плагінів каналу. Імпортуйте з `plugin-sdk/plugin-test-runtime` або `plugin-sdk/channel-test-helpers` | +| `createTestPluginApi` | Створює мінімальний мок API Plugin для прямих модульних тестів реєстрації. Імпортуйте з `plugin-sdk/plugin-test-api` | +| `expectChannelInboundContextContract` | Перевіряє форму вхідного контексту каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `installChannelOutboundPayloadContractSuite` | Підключає набір контрактних тестів для вихідного payload каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `createStartAccountContext` | Створює контексти життєвого циклу облікового запису каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `installChannelActionsContractSuite` | Підключає загальний набір контрактних тестів для дій із повідомленнями каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `installChannelSetupContractSuite` | Підключає загальний набір контрактних тестів для налаштування каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `installChannelStatusContractSuite` | Підключає загальний набір контрактних тестів для статусу каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `expectDirectoryIds` | Перевіряє id директорій із функції списку директорій. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `describePluginRegistrationContract` | Підключає перевірки контракту реєстрації Plugin. Імпортуйте з `plugin-sdk/plugin-test-contracts` | +| `registerSingleProviderPlugin` | Реєструє один Plugin провайдера в smoke-тестах завантажувача. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `registerProviderPlugin` | Захоплює всі типи провайдерів з одного Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `registerProviderPlugins` | Захоплює реєстрації провайдерів у кількох Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `requireRegisteredProvider` | Перевіряє, що колекція провайдерів містить id. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `createRuntimeEnv` | Створює змокане середовище виконання CLI/Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `createPluginSetupWizardStatus` | Створює допоміжні засоби статусу налаштування для плагінів каналів. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `describeOpenAIProviderRuntimeContract` | Підключає перевірки контракту середовища виконання для сімейства провайдерів. Імпортуйте з `plugin-sdk/provider-test-contracts` | +| `expectExplicitVideoGenerationCapabilities` | Перевіряє, що відеопровайдери явно оголошують можливості режиму генерації. Імпортуйте з `plugin-sdk/provider-test-contracts` | +| `expectExplicitMusicGenerationCapabilities` | Перевіряє, що музичні провайдери явно оголошують можливості генерації/редагування. Імпортуйте з `plugin-sdk/provider-test-contracts` | +| `mockSuccessfulDashscopeVideoTask` | Підключає успішну відповідь для відеозавдання, сумісного з DashScope. Імпортуйте з `plugin-sdk/provider-test-contracts` | +| `getProviderHttpMocks` | Надає доступ до опційних Vitest-моків HTTP/auth провайдерів. Імпортуйте з `plugin-sdk/provider-http-test-mocks` | +| `installProviderHttpMockCleanup` | Скидає HTTP/auth-моки провайдерів після кожного тесту. Імпортуйте з `plugin-sdk/provider-http-test-mocks` | +| `installCommonResolveTargetErrorCases` | Спільні тестові сценарії для обробки помилок розв’язання цілей. Імпортуйте з `plugin-sdk/channel-target-testing` | +| `shouldAckReaction` | Перевіряє, чи повинен канал додати ack-реакцію. Імпортуйте з `plugin-sdk/channel-feedback` | +| `removeAckReactionAfterReply` | Видаляє ack-реакцію після доставки відповіді. Імпортуйте з `plugin-sdk/channel-feedback` | +| `createTestRegistry` | Створює фікстуру реєстру плагінів каналів. Імпортуйте з `plugin-sdk/plugin-test-runtime` або `plugin-sdk/channel-test-helpers` | | `createEmptyPluginRegistry` | Створює порожню фікстуру реєстру плагінів. Імпортуйте з `plugin-sdk/plugin-test-runtime` або `plugin-sdk/channel-test-helpers` | -| `setActivePluginRegistry` | Встановлює фікстуру реєстру для тестів runtime плагіна. Імпортуйте з `plugin-sdk/plugin-test-runtime` або `plugin-sdk/channel-test-helpers` | -| `createRequestCaptureJsonFetch` | Захоплює JSON-запити fetch у тестах допоміжних медіа-функцій. Імпортуйте з `plugin-sdk/test-env` | -| `withFetchPreconnect` | Виконує тести fetch з установленими хуками preconnect. Імпортуйте з `plugin-sdk/test-env` | -| `withEnv` / `withEnvAsync` | Тимчасово підміняє змінні середовища. Імпортуйте з `plugin-sdk/test-env` | -| `createTempHomeEnv` / `withTempDir` | Створює ізольовані фікстури файлової системи для тестів. Імпортуйте з `plugin-sdk/test-env` | -| `createMockServerResponse` | Створює мінімальний мок відповіді HTTP-сервера. Імпортуйте з `plugin-sdk/test-env` | -| `createCliRuntimeCapture` | Захоплює вивід runtime CLI у тестах. Імпортуйте з `plugin-sdk/test-fixtures` | -| `createSandboxTestContext` | Створює контексти тестування sandbox. Імпортуйте з `plugin-sdk/test-fixtures` | -| `writeSkill` | Записує фікстури Skills. Імпортуйте з `plugin-sdk/test-fixtures` | -| `makeAgentAssistantMessage` | Створює фікстури повідомлень транскрипту агента. Імпортуйте з `plugin-sdk/test-fixtures` | -| `peekSystemEvents` / `resetSystemEventsForTest` | Переглядає та скидає фікстури системних подій. Імпортуйте з `plugin-sdk/test-fixtures` | -| `sanitizeTerminalText` | Очищає вивід термінала для перевірок. Імпортуйте з `plugin-sdk/test-fixtures` | -| `countLines` / `hasBalancedFences` | Перевіряє форму chunking-виводу. Імпортуйте з `plugin-sdk/test-fixtures` | -| `runProviderCatalog` | Виконує хук каталогу провайдерів із тестовими залежностями | -| `resolveProviderWizardOptions` | Розв’язує варіанти майстра налаштування провайдера у контрактних тестах | -| `resolveProviderModelPickerEntries` | Розв’язує елементи вибору моделей провайдера у контрактних тестах | -| `buildProviderPluginMethodChoice` | Створює id варіантів майстра провайдера для перевірок | -| `setProviderWizardProvidersResolverForTest` | Впроваджує провайдери майстра для ізольованих тестів | -| `createProviderUsageFetch` | Створює фікстури fetch використання провайдера | -| `useFrozenTime` / `useRealTime` | Заморожує та відновлює таймери для чутливих до часу тестів. Імпортуйте з `plugin-sdk/test-env` | -| `createTestWizardPrompter` | Створює змоканий prompter майстра налаштування | -| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow | -| `typedCases` | Зберігає літеральні типи для таблично-орієнтованих тестів. Імпортуйте з `plugin-sdk/test-fixtures` | +| `setActivePluginRegistry` | Встановлює фікстуру реєстру для тестів середовища виконання Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` або `plugin-sdk/channel-test-helpers` | +| `createRequestCaptureJsonFetch` | Захоплює JSON fetch-запити в тестах допоміжних медіафункцій. Імпортуйте з `plugin-sdk/test-env` | +| `withFetchPreconnect` | Запускає fetch-тести з установленими preconnect-хуками. Імпортуйте з `plugin-sdk/test-env` | +| `withEnv` / `withEnvAsync` | Тимчасово змінює змінні середовища. Імпортуйте з `plugin-sdk/test-env` | +| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові фікстури для тестів. Імпортуйте з `plugin-sdk/test-env` | +| `createMockServerResponse` | Створює мінімальний мок відповіді HTTP-сервера. Імпортуйте з `plugin-sdk/test-env` | +| `createCliRuntimeCapture` | Захоплює вивід середовища виконання CLI у тестах. Імпортуйте з `plugin-sdk/test-fixtures` | +| `createSandboxTestContext` | Створює тестові контексти sandbox. Імпортуйте з `plugin-sdk/test-fixtures` | +| `writeSkill` | Записує фікстури Skills. Імпортуйте з `plugin-sdk/test-fixtures` | +| `makeAgentAssistantMessage` | Створює фікстури повідомлень стенограми агента. Імпортуйте з `plugin-sdk/test-fixtures` | +| `peekSystemEvents` / `resetSystemEventsForTest` | Переглядає та скидає фікстури системних подій. Імпортуйте з `plugin-sdk/test-fixtures` | +| `sanitizeTerminalText` | Очищає вивід термінала для перевірок. Імпортуйте з `plugin-sdk/test-fixtures` | +| `countLines` / `hasBalancedFences` | Перевіряє форму chunking-виводу. Імпортуйте з `plugin-sdk/test-fixtures` | +| `runProviderCatalog` | Виконує хук каталогу провайдерів із тестовими залежностями | +| `resolveProviderWizardOptions` | Розв’язує варіанти майстра налаштування провайдера в контрактних тестах | +| `resolveProviderModelPickerEntries` | Розв’язує елементи вибору моделей провайдера в контрактних тестах | +| `buildProviderPluginMethodChoice` | Створює id варіантів майстра провайдера для перевірок | +| `setProviderWizardProvidersResolverForTest` | Впроваджує провайдерів майстра для ізольованих тестів | +| `createProviderUsageFetch` | Створює фікстури fetch для використання провайдера | +| `useFrozenTime` / `useRealTime` | Заморожує та відновлює таймери для тестів, чутливих до часу. Імпортуйте з `plugin-sdk/test-env` | +| `createTestWizardPrompter` | Створює змоканий prompter майстра налаштування | +| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow | +| `typedCases` | Зберігає літеральні типи для таблично-орієнтованих тестів. Імпортуйте з `plugin-sdk/test-fixtures` | -Набори контрактних тестів bundled-плагінів також використовують підшляхи SDK тестування для допоміжних засобів фікстур реєстру, маніфесту, публічних артефактів і runtime, призначених лише для тестів. Набори тільки для core, які залежать від bundled-інвентарю OpenClaw, залишаються в `src/plugins/contracts`. -Для нових тестів extension використовуйте документований цільовий підшлях SDK, наприклад +Набори контрактних тестів для вбудованих плагінів також використовують підшляхи SDK для тестування для допоміжних засобів тестових фікстур реєстру, маніфесту, публічних артефактів і runtime. Набори лише для core, які залежать від вбудованого інвентаря OpenClaw, залишаються в `src/plugins/contracts`. +Нові тести розширень тримайте на документованому спеціалізованому підшляху SDK, наприклад `plugin-sdk/plugin-test-api`, `plugin-sdk/channel-contract-testing`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/plugin-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/provider-test-contracts`, -`plugin-sdk/test-env` або `plugin-sdk/test-fixtures`, замість імпорту з -широкого сумісного barrel `plugin-sdk/testing`, файлів репозиторію `src/**` або -напряму з проміжних модулів репозиторію `test/helpers/plugins/*`. +`plugin-sdk/provider-http-test-mocks`, `plugin-sdk/test-env` або +`plugin-sdk/test-fixtures`, замість імпортування широкого суміснісного barrel `plugin-sdk/testing`, +файлів репозиторію `src/**` або напряму мостів репозиторію `test/helpers/plugins/*`. ### Типи -Цільові підшляхи тестування також повторно експортують типи, корисні у файлах тестів: +Спеціалізовані підшляхи тестування також повторно експортують типи, корисні у тестових файлах: ```typescript import type { @@ -132,25 +141,26 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types"; import type { MockFn, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/plugin-test-runtime"; ``` -## Тестування розв’язання цілі +## Тестування розв’язання цілей -Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для розв’язання цілі каналу: +Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні сценарії помилок для +розв’язання цілей каналу: ```typescript import { describe } from "vitest"; import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing"; -describe("розв’язання цілі my-channel", () => { +describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // Логіка розв’язання цілі вашого каналу + // Your channel's target resolution logic return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // Додайте специфічні для каналу тестові випадки - it("має розв’язувати цілі @username", () => { + // Add channel-specific test cases + it("should resolve @username targets", () => { // ... }); }); @@ -160,25 +170,32 @@ describe("розв’язання цілі my-channel", () => { ### Тестування контрактів реєстрації -Unit-тести, які передають вручну написаний мок `api` до `register(api)`, не перевіряють acceptance gates завантажувача OpenClaw. Додайте принаймні один smoke-тест із використанням завантажувача для кожної поверхні реєстрації, від якої залежить ваш плагін, особливо для hooks і ексклюзивних можливостей, таких як memory. +Модульні тести, які передають вручну написаний мок `api` до `register(api)`, не перевіряють +ворота прийняття завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі завантажувача +для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для хуків і +ексклюзивних можливостей, таких як пам’ять. -Справжній завантажувач відхиляє реєстрацію плагіна, якщо відсутні обов’язкові метадані або якщо плагін викликає API можливості, якою він не володіє. Наприклад, -`api.registerHook(...)` вимагає назву hook, а -`api.registerMemoryCapability(...)` вимагає, щоб маніфест плагіна або експортована точка входу оголошували `kind: "memory"`. +Справжній завантажувач відхиляє реєстрацію Plugin, якщо бракує потрібних метаданих або якщо +Plugin викликає API можливості, якою він не володіє. Наприклад, +`api.registerHook(...)` вимагає назву хука, а +`api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортований запис +оголошував `kind: "memory"`. -### Тестування доступу до конфігурації runtime +### Тестування доступу до runtime-конфігурації -Для тестування bundled-плагінів каналів віддавайте перевагу спільному моку runtime плагіна з `openclaw/plugin-sdk/channel-test-helpers`. -Його застарілі моки `runtime.config.loadConfig()` і -`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилки, щоб тести виявляли нове використання API сумісності. Перевизначайте ці моки лише тоді, коли тест явно покриває застарілу поведінку сумісності. +Віддавайте перевагу спільному моку runtime Plugin з `openclaw/plugin-sdk/channel-test-helpers` +під час тестування вбудованих плагінів каналів. Його застарілі моки `runtime.config.loadConfig()` і +`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове +використання API сумісності. Перевизначайте ці моки лише тоді, коли тест +явно покриває застарілу поведінку сумісності. -### Unit-тестування плагіна каналу +### Модульне тестування плагіна каналу ```typescript import { describe, it, expect, vi } from "vitest"; -describe("плагін my-channel", () => { - it("має розв’язувати обліковий запис із конфігурації", () => { +describe("my-channel plugin", () => { + it("should resolve account from config", () => { const cfg = { channels: { "my-channel": { @@ -192,7 +209,7 @@ describe("плагін my-channel", () => { expect(account.token).toBe("test-token"); }); - it("має перевіряти обліковий запис без materializing секретів", () => { + it("should inspect account without materializing secrets", () => { const cfg = { channels: { "my-channel": { token: "test-token" }, @@ -202,22 +219,22 @@ describe("плагін my-channel", () => { const inspection = myPlugin.setup.inspectAccount(cfg, undefined); expect(inspection.configured).toBe(true); expect(inspection.tokenStatus).toBe("available"); - // Значення токена не розкривається + // No token value exposed expect(inspection).not.toHaveProperty("token"); }); }); ``` -### Unit-тестування плагіна провайдера +### Модульне тестування плагіна провайдера ```typescript import { describe, it, expect } from "vitest"; -describe("плагін my-provider", () => { - it("має розв’язувати динамічні моделі", () => { +describe("my-provider plugin", () => { + it("should resolve dynamic models", () => { const model = myProvider.resolveDynamicModel({ modelId: "custom-model-v2", - // ... контекст + // ... context }); expect(model.id).toBe("custom-model-v2"); @@ -225,10 +242,10 @@ describe("плагін my-provider", () => { expect(model.api).toBe("openai-completions"); }); - it("має повертати каталог, коли ключ API доступний", async () => { + it("should return catalog when API key is available", async () => { const result = await myProvider.catalog.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), - // ... контекст + // ... context }); expect(result?.provider?.models).toHaveLength(2); @@ -236,9 +253,9 @@ describe("плагін my-provider", () => { }); ``` -### Мокування runtime плагіна +### Мокування runtime Plugin -Для коду, що використовує `createPluginRuntimeStore`, замокуйте runtime у тестах: +Для коду, який використовує `createPluginRuntimeStore`, мокуйте runtime у тестах: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -249,42 +266,42 @@ const store = createPluginRuntimeStore({ errorMessage: "test runtime not set", }); -// У налаштуванні тесту +// In test setup const mockRuntime = { agent: { resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"), - // ... інші моки + // ... other mocks }, config: { current: vi.fn(() => ({}) as const), mutateConfigFile: vi.fn(), replaceConfigFile: vi.fn(), }, - // ... інші простори імен + // ... other namespaces } as unknown as PluginRuntime; store.setRuntime(mockRuntime); -// Після тестів +// After tests store.clearRuntime(); ``` -### Тестування з per-instance stubs +### Тестування з per-instance stub -Віддавайте перевагу per-instance stubs замість мутації prototype: +Віддавайте перевагу per-instance stub замість мутації прототипу: ```typescript -// Бажано: per-instance stub +// Preferred: per-instance stub const client = new MyChannelClient(); client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); -// Уникайте: мутації prototype +// Avoid: prototype mutation // MyChannelClient.prototype.sendMessage = vi.fn(); ``` ## Контрактні тести (плагіни в репозиторії) -Bundled-плагіни мають контрактні тести, які перевіряють право власності на реєстрацію: +Вбудовані плагіни мають контрактні тести, які перевіряють належність реєстрації: ```bash pnpm test -- src/plugins/contracts/ @@ -295,9 +312,9 @@ pnpm test -- src/plugins/contracts/ - Які плагіни реєструють які провайдери - Які плагіни реєструють які мовленнєві провайдери - Коректність форми реєстрації -- Відповідність контракту runtime +- Відповідність runtime-контракту -### Запуск тестів з обмеженою областю +### Запуск scoped-тестів Для конкретного плагіна: @@ -313,31 +330,32 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Примусове застосування lint (плагіни в репозиторії) +## Lint-контроль (плагіни в репозиторії) -`pnpm check` примусово застосовує три правила для плагінів у репозиторії: +Три правила перевіряються через `pnpm check` для плагінів у репозиторії: 1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється -2. **Без прямих імпортів із `src/`** -- плагіни не можуть напряму імпортувати `../../src/` +2. **Без прямих імпортів `src/`** -- плагіни не можуть напряму імпортувати `../../src/` 3. **Без самоімпортів** -- плагіни не можуть імпортувати власний підшлях `plugin-sdk/` -Зовнішні плагіни не підпадають під дію цих правил lint, але дотримуватися тих самих шаблонів рекомендується. +Зовнішні плагіни не підпадають під ці lint-правила, але дотримуватися тих самих +шаблонів рекомендується. ## Конфігурація тестування OpenClaw використовує Vitest із порогами покриття V8. Для тестів плагінів: ```bash -# Запустити всі тести +# Run all tests pnpm test -# Запустити тести конкретного плагіна +# Run specific plugin tests pnpm test -- /my-channel/src/channel.test.ts -# Запустити з фільтром за конкретною назвою тесту +# Run with a specific test name filter pnpm test -- /my-channel/ -t "resolves account" -# Запустити з coverage +# Run with coverage pnpm test:coverage ``` @@ -350,6 +368,6 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту -- [Плагіни каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс плагіна каналу -- [Плагіни провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- hooks плагіна провайдера +- [Плагіни каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс плагінів каналів +- [Плагіни провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- хуки плагінів провайдерів - [Створення плагінів](/uk/plugins/building-plugins) -- посібник для початку роботи