diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index e2af4a51c..315cd87f2 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,67 +1,67 @@ --- read_when: - Робота над функціями каналу Discord -summary: Стан підтримки бота Discord, можливості та налаштування +summary: Стан підтримки бота Discord, можливості та конфігурація title: Discord x-i18n: - generated_at: "2026-04-29T21:05:30Z" + generated_at: "2026-04-30T00:56:00Z" model: gpt-5.5 provider: openai - source_hash: 2d374742a097682f33529f93709978f21b63a94cd4da803ff78ff8dfcb1f9b81 + source_hash: e9f31af2801e7faf6456d4452a5f43b0e42a067b86b7e562c308fa450a847356 source_path: channels/discord.md workflow: 16 --- -Готово для особистих повідомлень і каналів гільдій через офіційний Discord gateway. +Готово для DM і каналів гільдій через офіційний Discord gateway. - - Особисті повідомлення Discord за замовчуванням працюють у режимі сполучення. + + Discord DM за замовчуванням переходять у режим спарювання. Нативна поведінка команд і каталог команд. - Міжканальна діагностика та процес відновлення. + Міжканальна діагностика та потік відновлення. ## Швидке налаштування -Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). +Вам потрібно створити нову програму з ботом, додати бота на свій сервер і спарувати його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). - - Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть його, наприклад, "OpenClaw". + + Перейдіть до [Порталу розробників Discord](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть її, наприклад, "OpenClaw". Натисніть **Bot** на бічній панелі. Установіть **Username** на будь-яку назву, якою ви називаєте свого агента OpenClaw. - Залишаючись на сторінці **Bot**, прокрутіть униз до **Privileged Gateway Intents** і ввімкніть: + Залишаючись на сторінці **Bot**, прокрутіть униз до **Privileged Gateway Intents** і увімкніть: - **Message Content Intent** (обов’язково) - - **Server Members Intent** (рекомендовано; обов’язково для allowlist ролей і зіставлення імен з ID) + - **Server Members Intent** (рекомендовано; потрібно для allowlist ролей і зіставлення імен з ID) - **Presence Intent** (необов’язково; потрібно лише для оновлень присутності) - Прокрутіть назад угору на сторінці **Bot** і натисніть **Reset Token**. + Прокрутіть угору на сторінці **Bot** і натисніть **Reset Token**. - Попри назву, це створює ваш перший токен — нічого насправді не "скидається". + Попри назву, це генерує ваш перший токен — нічого не "скидається". - Скопіюйте токен і збережіть його. Це ваш **Bot Token**, і він незабаром знадобиться. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він скоро знадобиться. - - Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з потрібними дозволами, щоб додати бота на сервер. + + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з правильними дозволами, щоб додати бота на свій сервер. - Прокрутіть униз до **OAuth2 URL Generator** і ввімкніть: + Прокрутіть униз до **OAuth2 URL Generator** і увімкніть: - `bot` - `applications.commands` @@ -77,31 +77,31 @@ x-i18n: - Attach Files - Add Reactions (необов’язково) - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в тредах Discord, зокрема у сценаріях форумів або медіаканалів, які створюють чи продовжують тред, також увімкніть **Send Messages in Threads**. - Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте бачити свого бота на сервері Discord. + Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в тредах Discord, зокрема у робочих потоках форумних або медіаканалів, які створюють чи продовжують тред, також увімкніть **Send Messages in Threads**. + Скопіюйте згенерований URL унизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб під’єднатися. Тепер ви маєте бачити свого бота на сервері Discord. - - Повернувшись у застосунок Discord, потрібно ввімкнути режим розробника, щоб копіювати внутрішні ID. + + Повернувшись у програму Discord, потрібно увімкнути режим розробника, щоб копіювати внутрішні ID. - 1. Натисніть **User Settings** (іконка шестерні поруч з аватаром) → **Advanced** → увімкніть **Developer Mode** - 2. Клацніть правою кнопкою **іконку сервера** на бічній панелі → **Copy Server ID** - 3. Клацніть правою кнопкою **власний аватар** → **Copy User ID** + 1. Натисніть **User Settings** (значок шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** + 2. Клацніть правою кнопкою вашу **іконку сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою ваш **власний аватар** → **Copy User ID** - Збережіть **Server ID** і **User ID** разом із Bot Token — на наступному кроці ви надішлете всі три значення до OpenClaw. + Збережіть ваші **Server ID** і **User ID** поряд із Bot Token — на наступному кроці ви надішлете всі три до OpenClaw. - - Щоб сполучення працювало, Discord має дозволяти боту надсилати вам особисті повідомлення. Клацніть правою кнопкою **іконку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. + + Щоб спарювання працювало, Discord має дозволяти вашому боту надсилати вам DM. Клацніть правою кнопкою вашу **іконку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (зокрема ботам) надсилати вам особисті повідомлення. Залиште це ввімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути особисті повідомлення після сполучення. + Це дозволяє учасникам сервера (зокрема ботам) надсилати вам DM. Залиште це ввімкненим, якщо хочете використовувати Discord DM з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути DM після спарювання. - Токен бота Discord є секретом (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати агенту. + Токен вашого бота Discord — це секрет (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати своєму агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,18 +120,19 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - Якщо OpenClaw уже працює як фонова служба, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й заново запустивши процес `openclaw gateway run`. - Для встановлень як керованої служби запустіть `openclaw gateway install` з оболонки, де присутній `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб служба могла розв’язати env SecretRef після перезапуску. + Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й повторно запустивши процес `openclaw gateway run`. + Для інсталяцій керованого сервісу запустіть `openclaw gateway install` з shell, де присутня `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб сервіс міг розв’язати env SecretRef після перезапуску. + Якщо ваш хост заблокований або обмежений за частотою запитів під час стартового пошуку програми в Discord, задайте ID програми/клієнта Discord з Порталу розробників, щоб запуск міг пропустити цей REST-виклик. Використовуйте `channels.discord.applicationId` для типового облікового запису або `channels.discord.accounts..applicationId`, коли запускаєте кілька ботів Discord. - + - Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому. Якщо Discord є вашим першим каналом, натомість використайте вкладку CLI / конфігурації. + Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому. Якщо Discord — ваш перший канал, натомість використайте вкладку CLI / конфігурація. - > "Я вже задав токен бота Discord у конфігурації. Завершіть налаштування Discord з User ID `` і Server ID ``." + > "Я вже задав токен свого бота Discord у конфігурації. Завершіть налаштування Discord з User ID `` і Server ID ``." Якщо ви віддаєте перевагу файловій конфігурації, задайте: @@ -151,27 +152,49 @@ openclaw gateway } ``` - Env fallback для облікового запису за замовчуванням: + Env fallback для типового облікового запису: ```bash DISCORD_BOT_TOKEN=... ``` - Для скриптового або віддаленого налаштування запишіть той самий блок JSON5 за допомогою `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім повторно запустіть без `--dry-run`. Значення `token` у відкритому тексті підтримуються. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Для скриптового або віддаленого налаштування запишіть той самий блок JSON5 за допомогою `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім повторно запустіть без `--dry-run`. Значення `token` у відкритому тексті підтримуються. Значення SecretRef також підтримуються для `channels.discord.token` через провайдери env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + + Для кількох ботів Discord тримайте токен кожного бота та ID програми в його обліковому записі. Верхньорівневий `channels.discord.applicationId` успадковується обліковими записами, тому задавайте його там лише тоді, коли кожен обліковий запис має використовувати той самий ID програми. + +```json5 +{ + channels: { + discord: { + enabled: true, + accounts: { + personal: { + token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" }, + applicationId: "111111111111111111", + }, + work: { + token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" }, + applicationId: "222222222222222222", + }, + }, + }, + }, +} +``` - - Дочекайтеся, поки gateway буде запущено, а потім напишіть своєму боту в Discord в особисті повідомлення. Він відповість кодом сполучення. + + Зачекайте, доки gateway запрацює, а потім напишіть своєму боту в DM у Discord. Він відповість кодом спарювання. - Надішліть код сполучення своєму агенту в наявному каналі: + Надішліть код спарювання своєму агенту в наявному каналі: - > "Схвали цей код сполучення Discord: ``" + > "Підтвердь цей код спарювання Discord: ``" @@ -183,26 +206,26 @@ openclaw pairing approve discord - Коди сполучення спливають через 1 годину. + Коди спарювання спливають через 1 годину. - Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через особисті повідомлення. + Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через DM. -Розв’язання токенів враховує обліковий запис. Значення токена з конфігурації мають пріоритет над env fallback. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. -Якщо два ввімкнені облікові записи Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один gateway monitor для цього токена. Токен із конфігурації має пріоритет над default env fallback; інакше перший увімкнений обліковий запис перемагає, а дубльований обліковий запис повідомляється як вимкнений. -Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується саме для цього виклику. Це стосується дій надсилання та дій стилю читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторних спроб усе одно беруться з вибраного облікового запису в активному знімку runtime. +Розв’язання токенів враховує обліковий запис. Значення токена в конфігурації мають пріоритет над env fallback. `DISCORD_BOT_TOKEN` використовується лише для типового облікового запису. +Якщо два ввімкнені облікові записи Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один монітор gateway для цього токена. Токен із конфігурації має пріоритет над типовим env fallback; інакше перемагає перший увімкнений обліковий запис, а дубльований обліковий запис повідомляється як вимкнений. +Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується для цього виклику. Це застосовується до дій надсилання та читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторних спроб усе одно беруться з вибраного облікового запису в активному знімку runtime. ## Рекомендовано: налаштуйте робочий простір гільдії -Після того як особисті повідомлення запрацюють, можна налаштувати сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента зі своїм контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. +Коли DM запрацюють, ви можете налаштувати свій сервер Discord як повний робочий простір, де кожен канал отримує власну сесію агента зі своїм контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. - - Це дозволяє вашому агенту відповідати в будь-якому каналі на сервері, а не лише в особистих повідомленнях. + + Це дозволяє вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в DM. @@ -232,13 +255,13 @@ openclaw pairing approve discord - За замовчуванням ваш агент відповідає в каналах гільдії лише коли його згадали через @mention. Для приватного сервера ви, ймовірно, захочете, щоб він відповідав на кожне повідомлення. + За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його @згадали. Для приватного сервера ви, ймовірно, хочете, щоб він відповідав на кожне повідомлення. - У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно надсилати явно за допомогою інструмента `message`, тож агент може за замовчуванням лишатися пасивним і публікувати лише тоді, коли вирішить, що відповідь у канал корисна. + У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно надсилати явно за допомогою інструмента `message`, тому агент може за замовчуванням залишатися непомітним і публікувати лише тоді, коли вирішить, що відповідь у каналі корисна. - > "Дозволь моєму агенту відповідати на цьому сервері без потреби бути @mentioned" + > "Дозволь моєму агенту відповідати на цьому сервері без потреби бути @згаданим" Задайте `requireMention: false` у конфігурації гільдії: @@ -265,53 +288,53 @@ openclaw pairing approve discord - За замовчуванням довготривала пам’ять (MEMORY.md) завантажується лише в сесіях особистих повідомлень. Канали гільдії не завантажують MEMORY.md автоматично. + За замовчуванням довгострокова пам’ять (MEMORY.md) завантажується лише в сесіях DM. Канали гільдії не завантажують MEMORY.md автоматично. - > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо потрібен довготривалий контекст із MEMORY.md." + > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довгостроковий контекст із MEMORY.md." - Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони вставляються в кожну сесію). Зберігайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. + Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони інжектуються в кожну сесію). Тримайте довгострокові нотатки в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. -Тепер створіть кілька каналів на своєму сервері Discord і почніть спілкуватися. Ваш агент бачить назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що відповідає вашому робочому процесу. +Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкуватися. Ваш агент може бачити назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що підходить вашому робочому процесу. ## Модель runtime -- Gateway володіє підключенням Discord. -- Маршрутизація відповідей є детермінованою: вхідні відповіді Discord повертаються в Discord. -- Метадані гільдії/каналу Discord додаються до prompt моделі як недовірений - контекст, а не як видимий користувачу префікс відповіді. Якщо модель копіює цей конверт - назад, OpenClaw видаляє скопійовані метадані з вихідних відповідей і з +- Gateway керує з'єднанням із Discord. +- Маршрутизація відповідей є детермінованою: вхідні відповіді Discord повертаються до Discord. +- Метадані guild/channel Discord додаються до запиту моделі як ненадійний + контекст, а не як видимий користувачеві префікс відповіді. Якщо модель копіює цю обгортку + назад, OpenClaw вилучає скопійовані метадані з вихідних відповідей і з майбутнього контексту повторного відтворення. -- За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують основну сесію агента (`agent:main:main`). -- Канали гільдій є ізольованими ключами сесій (`agent::discord:channel:`). -- Групові особисті повідомлення за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). -- Нативні slash-команди запускаються в ізольованих командних сесіях (`agent::discord:slash:`), водночас усе ще передаючи `CommandTargetSessionKey` до маршрутизованої сесії розмови. -- Доставка текстових оголошень cron/heartbeat до Discord використовує фінальну - видиму асистенту відповідь один раз. Медіа та структуровані component payloads залишаються - багатоповідомленнєвими, коли агент випускає кілька deliverable payloads. +- За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують головний сеанс агента (`agent:main:main`). +- Канали guild ізольовані ключами сеансів (`agent::discord:channel:`). +- Групові DM ігноруються за замовчуванням (`channels.discord.dm.groupEnabled=false`). +- Нативні slash-команди виконуються в ізольованих командних сеансах (`agent::discord:slash:`), але все одно передають `CommandTargetSessionKey` до маршрутизованого сеансу розмови. +- Доставка оголошень текстових Cron/Heartbeat до Discord використовує остаточну + видиму асистенту відповідь один раз. Медіа та структуровані payload компонентів залишаються + багатоповідомними, коли агент видає кілька придатних до доставки payload. -## Форумні канали +## Канали форумів -Форумні та медіаканали Discord приймають лише публікації в тредах. OpenClaw підтримує два способи їх створення: +Форумні та медіаканали Discord приймають лише дописи в тредах. OpenClaw підтримує два способи їх створення: -- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити тред. Назва треду використовує перший непорожній рядок вашого повідомлення. -- Використайте `openclaw message thread create`, щоб створити тред напряму. Не передавайте `--message-id` для форумних каналів. +- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити тред. Заголовок треду використовує перший непорожній рядок вашого повідомлення. +- Використайте `openclaw message thread create`, щоб створити тред безпосередньо. Не передавайте `--message-id` для форумних каналів. -Приклад: надішліть до батьківського форуму, щоб створити тред +Приклад: надіслати до батьківського форуму, щоб створити тред ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Приклад: явно створіть форумний тред +Приклад: явно створити форумний тред ```bash openclaw message thread create --channel discord --target channel: \ @@ -322,7 +345,7 @@ openclaw message thread create --channel discord --target channel: \ ## Інтерактивні компоненти -OpenClaw підтримує контейнери components v2 Discord для повідомлень агентів. Використовуйте інструмент повідомлень із корисним навантаженням `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: @@ -330,21 +353,21 @@ OpenClaw підтримує контейнери components v2 Discord для п - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити використовувати кнопки, списки вибору та форми кілька разів, доки вони не завершать термін дії. +За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити кнопкам, меню вибору та формам використовуватися кілька разів, доки вони не завершать строк дії. -Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ідентифікатори користувачів Discord, теги або `*`). Коли це налаштовано, невідповідні користувачі отримують ефемерну відмову. +Щоб обмежити, хто може натискати кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі без збігу отримують ефемерну відмову. -Слеш-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного середовища виконання, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору ефемерна, і користуватися нею може лише користувач, який її викликав. +Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору є ефемерною, і використовувати її може лише користувач, який її викликав. Вкладення файлів: - Блоки `file` мають указувати на посилання вкладення (`attachment://`) - Надайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів -- Використовуйте `filename`, щоб перевизначити назву завантаження, коли вона має збігатися з посиланням вкладення +- Використовуйте `filename`, щоб перевизначити ім'я завантаження, коли воно має збігатися з посиланням вкладення Модальні форми: -- Додайте `components.modal` із до 5 полями +- Додайте `components.modal` з максимум 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -402,54 +425,54 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` -## Керування доступом і маршрутизація +## Контроль доступу та маршрутизація - `channels.discord.dmPolicy` керує доступом до DM. `channels.discord.allowFrom` є канонічним списком дозволів для DM. + `channels.discord.dmPolicy` керує доступом до DM. `channels.discord.allowFrom` є канонічним allowlist для DM. - `pairing` (за замовчуванням) - `allowlist` - `open` (вимагає, щоб `channels.discord.allowFrom` містив `"*"`) - `disabled` - Якщо політика DM не відкрита, невідомих користувачів блокують (або пропонують виконати спарювання в режимі `pairing`). + Якщо політика DM не є відкритою, невідомих користувачів блокують (або пропонують виконати pairing у режимі `pairing`). - Пріоритет для кількох облікових записів: + Пріоритетність кількох облікових записів: - `channels.discord.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - Для одного облікового запису `allowFrom` має пріоритет над застарілим `dm.allowFrom`. - - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не задані. + - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не встановлені. - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. - Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. + Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` мігрує їх у `dmPolicy` і `allowFrom`, коли може зробити це без зміни доступу. Формат цілі DM для доставки: - `user:` - згадка `<@id>` - Прості числові ідентифікатори зазвичай розпізнаються як ідентифікатори каналів, коли активне значення каналу за замовчуванням, але ідентифікатори, перелічені в ефективному списку дозволів DM `allowFrom` облікового запису, розглядаються як цілі користувацьких DM для сумісності. + Голі числові ID зазвичай розпізнаються як ID каналів, коли активне стандартне значення каналу, але ID, перелічені в ефективному DM `allowFrom` облікового запису, для сумісності трактуються як цілі користувацьких DM. - Обробкою гільдій керує `channels.discord.groupPolicy`: + Обробка guild керується `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Безпечна базова конфігурація, коли існує `channels.discord`, це `allowlist`. + Безпечний базовий рівень, коли існує `channels.discord`, це `allowlist`. Поведінка `allowlist`: - - гільдія має відповідати `channels.discord.guilds` (бажано `id`, приймається slug) - - необов’язкові списки дозволів відправників: `users` (рекомендовано стабільні ідентифікатори) і `roles` (лише ідентифікатори ролей); якщо налаштовано будь-який із них, відправники дозволені, коли вони відповідають `users` АБО `roles` - - прямий збіг імені/тега вимкнено за замовчуванням; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як режим сумісності на крайній випадок - - імена/теги підтримуються для `users`, але ідентифікатори безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів - - якщо для гільдії налаштовано `channels`, канали не зі списку забороняються - - якщо гільдія не має блока `channels`, усі канали в цій дозволеній гільдії дозволені + - guild має відповідати `channels.discord.guilds` (переважно `id`, slug приймається) + - необов'язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо будь-який із них налаштовано, відправники дозволені, коли вони збігаються з `users` АБО `roles` + - пряме зіставлення імен/тегів вимкнено за замовчуванням; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності + - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів + - якщо guild має налаштовані `channels`, канали не зі списку забороняються + - якщо guild не має блока `channels`, усі канали в цьому allowlisted guild дозволені Приклад: @@ -475,33 +498,33 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` - Якщо ви встановили лише `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, резервна поведінка середовища виконання — `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` — `open`. + Якщо ви встановили лише `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, runtime fallback — `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. - Повідомлення гільдії за замовчуванням проходять через перевірку згадки. + Повідомлення guild за замовчуванням вимагають згадки. Виявлення згадок охоплює: - явну згадку бота - - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) + - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - неявну поведінку відповіді боту в підтримуваних випадках - `requireMention` налаштовується для кожної гільдії/каналу (`channels.discord.guilds...`). - `ignoreOtherMentions` необов’язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). + `requireMention` налаштовується для кожного guild/каналу (`channels.discord.guilds...`). + `ignoreOtherMentions` необов'язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (крім @everyone/@here). Групові DM: - за замовчуванням: ігноруються (`dm.groupEnabled=false`) - - необов’язковий список дозволів через `dm.groupChannels` (ідентифікатори каналів або slugs) + - необов'язковий allowlist через `dm.groupChannels` (ID каналів або slug) ### Маршрутизація агентів на основі ролей -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдій Discord до різних агентів за ідентифікатором ролі. Прив’язки на основі ролей приймають лише ідентифікатори ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише гільдії. Якщо прив’язка також задає інші поля відповідності (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників guild Discord до різних агентів за ID ролі. Прив'язки на основі ролей приймають лише ID ролей і оцінюються після прив'язок peer або parent-peer та перед прив'язками лише до guild. Якщо прив'язка також задає інші поля збігу (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -525,25 +548,25 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` -## Нативні команди та авторизація команд +## Нативні команди та auth команд - `commands.native` за замовчуванням має значення `"auto"` і ввімкнено для Discord. -- Перевизначення для каналу: `channels.discord.commands.native`. +- Перевизначення для окремого каналу: `channels.discord.commands.native`. - `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. -- Авторизація нативних команд використовує ті самі списки дозволів/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимими в інтерфейсі Discord для користувачів без авторизації; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". +- Auth нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все одно можуть бути видимими в UI Discord для користувачів, які не авторизовані; виконання все одно застосовує auth OpenClaw і повертає "not authorized". -Див. [Слеш-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. +Див. [Slash-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. -Налаштування слеш-команд за замовчуванням: +Стандартні налаштування slash-команд: - `ephemeral: true` -## Докладно про функції +## Подробиці функцій - Discord підтримує теги відповіді у виводі агента: + Discord підтримує теги відповідей у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` @@ -555,21 +578,21 @@ OpenClaw підтримує контейнери components v2 Discord для п - `all` - `batched` - Примітка: `off` вимикає неявне гілкування відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. - `first` завжди додає неявне нативне посилання відповіді до першого вихідного повідомлення Discord для ходу. - `batched` додає неявне нативне посилання відповіді Discord лише тоді, коли - вхідний хід був debounce-пакетом із кількох повідомлень. Це корисно, - коли потрібні нативні відповіді переважно для неоднозначних швидких чатів, а не для кожного + Примітка: `off` вимикає неявне створення тредів відповідей. Явні теги `[[reply_to_*]]` все одно враховуються. + `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord за хід. + `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли + вхідний хід був debounced-пакетом із кількох повідомлень. Це корисно, + коли ви хочете мати нативні відповіді переважно для неоднозначних вибухових чатів, а не для кожного ходу з одним повідомленням. - Ідентифікатори повідомлень показуються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень відображаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. - OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення й редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` зіставляється з `partial` у Discord; `streamMode` є застарілим псевдонімом і мігрується автоматично. + OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` зіставляється з `partial` у Discord; `streamMode` є застарілим alias і мігрується автоматично. - За замовчуванням лишається `off`, бо редагування попереднього перегляду Discord швидко впираються в ліміти частоти, коли кілька ботів або Gateway використовують один обліковий запис. + За замовчуванням лишається `off`, оскільки попередні редагування Discord швидко наштовхуються на rate limits, коли кілька ботів або gateways спільно використовують обліковий запис. ```json5 { @@ -587,19 +610,19 @@ OpenClaw підтримує контейнери components v2 Discord для п ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` надсилає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). - - Медіа, помилки та фінальні відповіді з явною відповіддю скасовують очікувані редагування попереднього перегляду. + - `block` видає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). + - Медіа, помилки та фінальні відповіді з явним reply скасовують очікувані редагування попереднього перегляду. - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. - Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли потокове передавання `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потоковий попередній перегляд підтримує лише текст; медіавідповіді повертаються до звичайної доставки. Коли потоковий режим `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного стримінгу. - Контекст історії гільдії: + Контекст історії guild: - `channels.discord.historyLimit` за замовчуванням `20` - - резервно: `messages.groupChat.historyLimit` + - fallback: `messages.groupChat.historyLimit` - `0` вимикає Керування історією DM: @@ -610,25 +633,25 @@ OpenClaw підтримує контейнери components v2 Discord для п Поведінка гілок: - Гілки Discord маршрутизуються як сеанси каналів і успадковують конфігурацію батьківського каналу, якщо її не перевизначено. - - Сеанси гілок успадковують вибір `/model` рівня сеансу батьківського каналу як резерв лише для моделі; локальні вибори `/model` гілки все ще мають пріоритет, а історія батьківської транскрипції не копіюється, якщо не ввімкнено успадкування транскрипції. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автогілок заповнення з батьківської транскрипції. Перевизначення для облікових записів розташовані в `channels.discord.accounts..thread.inheritParent`. - - Реакції інструмента повідомлень можуть розпізнавати цілі DM `user:`. + - Сеанси гілок успадковують вибір `/model` на рівні сеансу батьківського каналу як резервний варіант лише для моделі; локальні для гілки вибори `/model` все одно мають пріоритет, а історія транскрипту батьківського каналу не копіюється, якщо не ввімкнено успадкування транскрипту. + - `channels.discord.thread.inheritParent` (типово `false`) вмикає для нових автоматичних гілок початкове наповнення з батьківського транскрипту. Перевизначення для окремого облікового запису розміщуються в `channels.discord.accounts..thread.inheritParent`. + - Реакції інструментів повідомлень можуть визначати цілі DM `user:`. - `guilds..channels..requireMention: false` зберігається під час резервної активації на етапі відповіді. - Теми каналів додаються як **ненадійний** контекст. Списки дозволів обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. + Теми каналів додаються як **ненадійний** контекст. Списки дозволених користувачів обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. - - Discord може прив’язати гілку до цілі сеансу, щоб подальші повідомлення в цій гілці продовжували маршрутизуватися до того самого сеансу (зокрема сеансів підагентів). + + Discord може привʼязати гілку до цілі сеансу, щоб подальші повідомлення в цій гілці й далі маршрутизувалися до того самого сеансу (зокрема сеансів субагентів). Команди: - - `/focus ` прив’язати поточну/нову гілку до цілі підагента/сеансу - - `/unfocus` видалити прив’язку поточної гілки - - `/agents` показати активні запуски та стан прив’язки - - `/session idle ` переглянути/оновити автоматичне скасування фокуса за неактивністю для сфокусованих прив’язок - - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок + - `/focus ` привʼязати поточну/нову гілку до цілі субагента/сеансу + - `/unfocus` прибрати привʼязку поточної гілки + - `/agents` показати активні запуски та стан привʼязки + - `/session idle ` переглянути/оновити автоматичне скасування фокуса за неактивності для сфокусованих привʼязок + - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих привʼязок Конфігурація: @@ -658,16 +681,16 @@ OpenClaw підтримує контейнери components v2 Discord для п - `session.threadBindings.*` задає глобальні типові значення. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - - `spawnSubagentSessions` має бути true, щоб автоматично створювати/прив’язувати потоки для `sessions_spawn({ thread: true })`. - - `spawnAcpSessions` має бути true, щоб автоматично створювати/прив’язувати потоки для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). - - Якщо прив’язки потоків вимкнені для облікового запису, `/focus` і пов’язані операції прив’язки потоків недоступні. + - `spawnSubagentSessions` має бути true, щоб автоматично створювати/привʼязувати гілки для `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` має бути true, щоб автоматично створювати/привʼязувати гілки для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). + - Якщо привʼязки гілок вимкнено для облікового запису, `/focus` і повʼязані операції привʼязки гілок недоступні. - Див. [Субагенти](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Довідник конфігурації](/uk/gateway/configuration-reference). + Див. [Субагенти](/uk/tools/subagents), [ACP-агенти](/uk/tools/acp-agents) і [Довідник конфігурації](/uk/gateway/configuration-reference). - - Для стабільних "always-on" робочих просторів ACP налаштуйте типізовані прив’язки ACP верхнього рівня, що спрямовують на розмови Discord. + + Для стабільних ACP-робочих просторів у режимі «завжди ввімкнено» налаштуйте типізовані привʼязки ACP верхнього рівня, спрямовані на розмови Discord. Шлях конфігурації: @@ -723,16 +746,16 @@ OpenClaw підтримує контейнери components v2 Discord для п Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або потік на місці й зберігає майбутні повідомлення в тому самому сеансі ACP. Повідомлення потоку успадковують прив’язку батьківського каналу. - - У прив’язаному каналі або потоці `/new` і `/reset` скидають той самий сеанс ACP на місці. Тимчасові прив’язки потоків можуть перевизначати визначення цілі, поки активні. - - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірній потік через `--thread auto|here`. + - `/acp spawn codex --bind here` привʼязує поточний канал або гілку на місці та зберігає майбутні повідомлення в тому самому сеансі ACP. Повідомлення гілки успадковують привʼязку батьківського каналу. + - У привʼязаному каналі або гілці `/new` і `/reset` скидають той самий сеанс ACP на місці. Тимчасові привʼязки гілок можуть перевизначати визначення цілі, доки активні. + - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/привʼязати дочірню гілку через `--thread auto|here`. - Див. [ACP Agents](/uk/tools/acp-agents) для деталей поведінки прив’язок. + Докладніше про поведінку привʼязок див. у [ACP-агентах](/uk/tools/acp-agents). - Режим сповіщень про реакції для кожної гільдії: + Режим сповіщень про реакції для окремої гільдії: - `off` - `own` (типово) @@ -755,15 +778,15 @@ OpenClaw підтримує контейнери components v2 Discord для п Примітки: - - Discord приймає unicode-емодзі або назви власних емодзі. + - Discord приймає unicode-емодзі або назви користувацьких емодзі. - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації, ініційовані каналом, увімкнені типово. + Записи конфігурації, ініційовані каналом, увімкнено типово. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). + Це впливає на потоки `/config set|unset` (коли функції команд увімкнено). Вимкнення: @@ -780,7 +803,7 @@ OpenClaw підтримує контейнери components v2 Discord для п - Маршрутизуйте Gateway WebSocket-трафік Discord і стартові REST-пошуки (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + Маршрутизуйте WebSocket-трафік Discord Gateway і стартові REST-пошуки (ID застосунку + визначення списку дозволених) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. ```json5 { @@ -792,7 +815,7 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` - Перевизначення для облікового запису: + Перевизначення для окремого облікового запису: ```json5 { @@ -828,10 +851,10 @@ OpenClaw підтримує контейнери components v2 Discord для п Примітки: - - allowlist можуть використовувати `pk:` - - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` + - списки дозволених можуть використовувати `pk:` + - показувані імена учасників зіставляються за іменем/слагом лише коли `channels.discord.dangerouslyAllowNameMatching: true` - пошуки використовують ID оригінального повідомлення та обмежені часовим вікном - - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо `allowBots=true` не встановлено + - якщо пошук не вдається, проксійовані повідомлення розглядаються як повідомлення бота й відкидаються, якщо `allowBots=true` не встановлено @@ -850,7 +873,7 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` - Приклад активності (власний статус є типовим типом активності): + Приклад активності (користувацький статус є типовим типом активності): ```json5 { @@ -880,13 +903,13 @@ OpenClaw підтримує контейнери components v2 Discord для п Мапа типів активності: - 0: Грає - - 1: Транслює (потрібен `activityUrl`) + - 1: Транслює (потребує `activityUrl`) - 2: Слухає - 3: Дивиться - - 4: Власний (використовує текст активності як стан статусу; емодзі необов’язковий) + - 4: Користувацький (використовує текст активності як стан статусу; емодзі необовʼязковий) - 5: Змагається - Приклад автоматичної присутності (сигнал стану runtime): + Приклад автоматичної присутності (сигнал справності середовища виконання): ```json5 { @@ -903,43 +926,43 @@ OpenClaw підтримує контейнери components v2 Discord для п } ``` - Автоматична присутність зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: + Автоматична присутність зіставляє доступність середовища виконання зі статусом Discord: справний => онлайн, деградований або невідомий => неактивний, вичерпаний або недоступний => не турбувати. Необовʼязкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (підтримує placeholder `{reason}`) + - `autoPresence.exhaustedText` (підтримує плейсхолдер `{reason}`) - - Discord підтримує обробку схвалень на основі кнопок у DM і може необов’язково публікувати запити на схвалення в початковому каналі. + + Discord підтримує обробку підтверджень на основі кнопок у DM і може необовʼязково публікувати запити підтвердження у вихідному каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовує fallback до `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.approvers` (необовʼязково; за можливості резервно використовує `commands.ownerAllowFrom`) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні exec-схвалення, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного схвалювача, або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить exec-схвалювачів із канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Встановіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт схвалень. + Discord автоматично вмикає нативні підтвердження виконання, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного підтверджувача: або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить підтверджувачів виконання з канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Задайте `enabled: false`, щоб явно вимкнути Discord як нативний клієнт підтверджень. - Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на схвалення та фінальні результати приватно. Спочатку він пробує Discord DM, коли власник, що викликає команду, має маршрут власника Discord; якщо він недоступний, використовується fallback до першого доступного маршруту власника з `commands.ownerAllowFrom`, наприклад Telegram. + Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити підтвердження та фінальні результати приватно. Спочатку він пробує Discord DM, коли власник, який викликає команду, має маршрут власника Discord; якщо це недоступно, він резервно використовує перший доступний маршрут власника з `commands.ownerAllowFrom`, наприклад Telegram. - Коли `target` має значення `channel` або `both`, запит на схвалення видимий у каналі. Лише визначені схвалювачі можуть використовувати кнопки; інші користувачі отримують ефемерну відмову. Запити на схвалення містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо отримати з ключа сеансу, OpenClaw використовує fallback до доставки в DM. + Коли `target` має значення `channel` або `both`, запит підтвердження видимий у каналі. Кнопки можуть використовувати лише визначені підтверджувачі; інші користувачі отримують ефемерну відмову. Запити підтвердження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу не можна вивести з ключа сеансу, OpenClaw резервно переходить до доставки через DM. - Discord також відображає спільні кнопки схвалення, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для схвалювачів і розсилання в канали. - Коли ці кнопки присутні, вони є основним UX для схвалення; OpenClaw - має додавати ручну команду `/approve` лише тоді, коли результат інструмента каже, - що чат-схвалення недоступні або ручне схвалення є єдиним шляхом. - Якщо нативний runtime схвалень Discord не активний, OpenClaw залишає - видимим локальний детермінований запит `/approve `. Якщо - runtime активний, але нативну картку неможливо доставити жодній цілі, - OpenClaw надсилає fallback-сповіщення в той самий чат із точною командою `/approve` - з очікуваного схвалення. + Discord також відображає спільні кнопки підтвердження, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для підтверджувачів і розсилання в канал. + Коли ці кнопки присутні, вони є основним UX підтверджень; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, + що чат-підтвердження недоступні або ручне підтвердження є єдиним шляхом. + Якщо нативне середовище виконання підтверджень Discord неактивне, OpenClaw залишає + локальний детермінований запит `/approve ` видимим. Якщо + середовище виконання активне, але нативну картку неможливо доставити до жодної цілі, + OpenClaw надсилає резервне сповіщення в той самий чат із точною командою `/approve` + з очікуваного підтвердження. - Gateway-автентифікація та визначення схвалень дотримуються спільного контракту клієнта Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID через `exec.approval.resolve`). Схвалення типово спливають через 30 хвилин. + Автентифікація Gateway і визначення підтверджень дотримуються спільного контракту клієнта Gateway (ID `plugin:` визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). Термін дії підтверджень типово спливає через 30 хвилин. - Див. [Exec approvals](/uk/tools/exec-approvals). + Див. [Підтвердження виконання](/uk/tools/exec-approvals). @@ -955,26 +978,26 @@ OpenClaw підтримує контейнери components v2 Discord для п - модерація: `timeout`, `kick`, `ban` - присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файлу), щоб встановити обкладинку запланованої події. +Дія `event-create` приймає необовʼязковий параметр `image` (URL або шлях до локального файлу), щоб задати зображення обкладинки запланованої події. -Шлюзи дій містяться в `channels.discord.actions.*`. +Шлюзи дій розміщуються в `channels.discord.actions.*`. -Типова поведінка шлюзів: +Типова поведінка шлюзу: -| Група дій | Типово | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | -| roles | вимкнено | -| moderation | вимкнено | -| presence | вимкнено | +| Група дій | За замовчуванням | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | +| roles | вимкнено | +| moderation | вимкнено | +| presence | вимкнено | -## UI Components v2 +## Інтерфейс компонентів v2 -OpenClaw використовує Discord components v2 для exec-схвалень і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для власного UI (розширено; потребує створення component payload через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. +OpenClaw використовує компоненти Discord v2 для підтверджень виконання та маркерів між контекстами. Дії з повідомленнями Discord також можуть приймати `components` для спеціального інтерфейсу (розширений варіант; потребує побудови payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. - `channels.discord.ui.components.accentColor` задає акцентний колір, який використовують контейнери компонентів Discord (hex). -- Задайте для кожного облікового запису через `channels.discord.accounts..ui.components.accentColor`. -- `embeds` ігноруються, коли присутні components v2. +- Для окремого облікового запису задавайте через `channels.discord.accounts..ui.components.accentColor`. +- `embeds` ігноруються, коли присутні компоненти v2. Приклад: @@ -994,7 +1017,7 @@ OpenClaw використовує Discord components v2 для exec-схвале ## Голос -Discord має дві окремі голосові поверхні: realtime **голосові канали** (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду з хвильовою формою). Gateway підтримує обидві. +Discord має дві окремі голосові поверхні: голосові канали реального часу (безперервні розмови) і вкладення голосових повідомлень (формат попереднього перегляду хвильової форми). Gateway підтримує обидва варіанти. ### Голосові канали @@ -1007,7 +1030,7 @@ Discord має дві окремі голосові поверхні: realtime * 5. Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). 6. Налаштуйте `channels.discord.voice`. -Використовуйте `/vc join|leave|status`, щоб керувати сеансами. Команда використовує стандартного агента облікового запису та дотримується тих самих правил списків дозволених і групової політики, що й інші команди Discord. +Використовуйте `/vc join|leave|status`, щоб керувати сесіями. Команда використовує агента за замовчуванням для облікового запису й дотримується тих самих правил списків дозволених і групової політики, що й інші команди Discord. ```bash /vc join channel: @@ -1045,33 +1068,33 @@ Discord має дві окремі голосові поверхні: realtime * Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- `voice.model` перевизначає LLM, що використовується лише для відповідей у голосовому каналі Discord. Залиште це неналаштованим, щоб успадкувати модель маршрутизованого агента. +- `voice.model` перевизначає LLM, який використовується лише для відповідей у голосовому каналі Discord. Залиште це поле незаданим, щоб успадкувати модель маршрутизованого агента. - STT використовує `tools.media.audio`; `voice.model` не впливає на транскрибування. -- Репліки голосової транскрипції отримують статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). -- Голос увімкнено за замовчуванням; установіть `channels.discord.voice.enabled=false`, щоб вимкнути голосове середовище виконання та Gateway intent `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` може явно перевизначати підписку на intent голосового стану. Залиште це неналаштованим, щоб intent слідував за `voice.enabled`. +- Ходи голосової транскрипції визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). +- Голос увімкнено за замовчуванням; задайте `channels.discord.voice.enabled=false`, щоб вимкнути голосовий runtime і Gateway intent `GuildVoiceStates`. +- `channels.discord.intents.voiceStates` може явно перевизначити підписку на intent стану голосу. Залиште це поле незаданим, щоб intent відповідав `voice.enabled`. - `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів приєднання `@discordjs/voice`. -- Стандартні значення `@discordjs/voice`: `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не налаштовано. -- OpenClaw також відстежує помилки розшифрування прийому та автоматично відновлюється, виходячи з голосового каналу й повторно приєднуючись до нього після повторюваних помилок у короткому проміжку часу. -- Якщо після оновлення в журналах прийому повторно з’являється `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінія `@discordjs/voice` містить upstream-виправлення padding з discord.js PR #11449, яке закрило issue discord.js #11419. +- Значення за замовчуванням `@discordjs/voice`: `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. +- OpenClaw також відстежує збої розшифрування під час отримання й автоматично відновлюється, виходячи з голосового каналу та повторно приєднуючись до нього після повторюваних збоїв у короткому проміжку часу. +- Якщо журнали отримання після оновлення знову й знову показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінійка `@discordjs/voice` містить upstream-виправлення padding з PR discord.js #11449, який закрив issue discord.js #11419. Конвеєр голосового каналу: -- PCM-захоплення Discord перетворюється на тимчасовий WAV-файл. +- Захоплення PCM з Discord перетворюється на тимчасовий WAV-файл. - `tools.media.audio` обробляє STT, наприклад `openai/gpt-4o-mini-transcribe`. - Транскрипція надсилається через звичайний вхідний потік і маршрутизацію Discord. -- `voice.model`, якщо налаштовано, перевизначає лише LLM відповіді для цієї репліки голосового каналу. -- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється в каналі, до якого виконано приєднання. +- `voice.model`, якщо задано, перевизначає лише LLM відповіді для цього ходу голосового каналу. +- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється в приєднаному каналі. Облікові дані визначаються для кожного компонента окремо: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. ### Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw генерує хвильову форму автоматично, але потребує `ffmpeg` і `ffprobe` на хості Gateway для перевірки й конвертації. +Голосові повідомлення Discord показують попередній перегляд хвильової форми й потребують аудіо OGG/Opus. OpenClaw автоматично генерує хвильову форму, але потребує `ffmpeg` і `ffprobe` на хості Gateway для перевірки та конвертації. -- Надайте **локальний шлях до файлу** (URL-адреси відхиляються). -- Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). -- Приймається будь-який аудіоформат; OpenClaw за потреби конвертує його в OGG/Opus. +- Надайте **локальний шлях до файлу** (URL відхиляються). +- Не вказуйте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). +- Приймається будь-який аудіоформат; OpenClaw за потреби конвертує в OGG/Opus. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1080,19 +1103,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Усунення несправностей - + - увімкніть Message Content Intent - - увімкніть Server Members Intent, коли ви залежите від визначення користувачів/учасників - - перезапустіть gateway після зміни intents + - увімкніть Server Members Intent, коли ви залежите від визначення користувача/учасника + - перезапустіть gateway після зміни intent - + - перевірте `groupPolicy` - перевірте список дозволених guild у `channels.discord.guilds` - - якщо існує мапа guild `channels`, дозволені лише перелічені канали + - якщо існує мапа `channels` для guild, дозволені лише перелічені канали - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1105,29 +1128,29 @@ openclaw logs --follow - + Поширені причини: - - `groupPolicy="allowlist"` без відповідного списку дозволених guild/channel + - `groupPolicy="allowlist"` без відповідного списку дозволених guild/каналів - `requireMention` налаштовано в неправильному місці (має бути під `channels.discord.guilds` або в записі каналу) - - відправника заблоковано списком дозволених `users` guild/channel + - відправника заблоковано списком дозволених `users` guild/каналу - + Типові журнали: - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Параметри черги Discord gateway: + Регулятори черги Discord gateway: - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` - - це керує лише роботою listener Discord gateway, а не тривалістю репліки агента + - це керує лише роботою слухача Discord gateway, а не тривалістю ходу агента - Discord не застосовує timeout, що належить каналу, до поставлених у чергу реплік агента. Message listeners передають роботу негайно, а поставлені в чергу запуски Discord зберігають порядок у межах сеансу, доки життєвий цикл session/tool/runtime не завершить або не перерве роботу. + Discord не застосовує тайм-аут, що належить каналу, до поставлених у чергу ходів агента. Слухачі повідомлень одразу передають роботу далі, а поставлені в чергу запуски Discord зберігають порядок у межах сесії, доки життєвий цикл сесії/інструмента/runtime не завершить або не перерве роботу. ```json5 { @@ -1147,50 +1170,50 @@ openclaw logs --follow - - OpenClaw отримує metadata Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартної URL-адреси gateway Discord і обмежуються за частотою в журналах. + + OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартного URL Gateway Discord і в журналах обмежуються за частотою. - Параметри timeout для metadata: + Регулятори тайм-ауту метаданих: - один обліковий запис: `channels.discord.gatewayInfoTimeoutMs` - кілька облікових записів: `channels.discord.accounts..gatewayInfoTimeoutMs` - - fallback env, коли config не налаштовано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - стандартно: `30000` (30 секунд), максимум: `120000` + - fallback env, коли конфігурацію не задано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - за замовчуванням: `30000` (30 секунд), максимум: `120000` - - Перевірки дозволів `channels status --probe` працюють лише для числових ідентифікаторів каналів. + + Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. Якщо ви використовуєте slug-ключі, зіставлення під час виконання все ще може працювати, але probe не може повністю перевірити дозволи. - + - DM вимкнено: `channels.discord.dm.enabled=false` - - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (legacy: `channels.discord.dm.policy`) - - очікується схвалення pairing у режимі `pairing` + - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) + - очікується підтвердження pairing у режимі `pairing` - + За замовчуванням повідомлення, створені ботами, ігноруються. - Якщо ви встановлюєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і списків дозволених, щоб уникнути циклічної поведінки. + Якщо ви задаєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і списків дозволених, щоб уникнути циклічної поведінки. Надавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. - - підтримуйте OpenClaw актуальним (`openclaw update`), щоб була присутня логіка відновлення прийому голосу Discord - - підтвердьте `channels.discord.voice.daveEncryption=true` (стандартно) - - почніть із `channels.discord.voice.decryptionFailureTolerance=24` (upstream-стандарт) і налаштовуйте лише за потреби + - підтримуйте OpenClaw актуальним (`openclaw update`), щоб була наявна логіка відновлення отримання голосу Discord + - підтвердьте `channels.discord.voice.daveEncryption=true` (за замовчуванням) + - почніть із `channels.discord.voice.decryptionFailureTolerance=24` (upstream-значення за замовчуванням) і налаштовуйте лише за потреби - стежте в журналах за: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - якщо помилки тривають після автоматичного повторного приєднання, зберіть журнали та порівняйте з upstream-історією прийому DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) + - якщо збої продовжуються після автоматичного повторного приєднання, зберіть журнали й порівняйте з upstream-історією отримання DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) @@ -1199,49 +1222,49 @@ openclaw logs --follow Основний довідник: [Довідник конфігурації - Discord](/uk/gateway/config-channels#discord). - + -- запуск/auth: `enabled`, `token`, `accounts.*`, `allowBots` +- запуск/автентифікація: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - команда: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` -- черга подій: `eventQueue.listenerTimeout` (бюджет listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- metadata gateway: `gatewayInfoTimeoutMs` +- черга подій: `eventQueue.listenerTimeout` (бюджет слухача), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` +- метадані gateway: `gatewayInfoTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставлення: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- streaming: `streaming` (legacy alias: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повторна спроба: `mediaMaxMb` (обмежує вихідні завантаження Discord, стандартно `100MB`), `retry` +- потокове передавання: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повторна спроба: `mediaMaxMb` (обмежує вихідні завантаження Discord, за замовчуванням `100MB`), `retry` - дії: `actions.*` -- присутність: `activity`, `status`, `activityType`, `activityUrl` +- presence: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- функції: `threadBindings`, top-level `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- функції: `threadBindings`, верхньорівневі `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` ## Безпека та експлуатація -- Розглядайте токени ботів як секрети (`DISCORD_BOT_TOKEN` бажано в керованих середовищах). +- Розглядайте токени ботів як секрети (у керованих середовищах бажано `DISCORD_BOT_TOKEN`). - Надавайте мінімально необхідні дозволи Discord. -- Якщо deploy/state команд застарів, перезапустіть gateway і повторно перевірте за допомогою `openclaw channels status --probe`. +- Якщо розгортання/стан команд застарілі, перезапустіть gateway і повторно перевірте за допомогою `openclaw channels status --probe`. ## Пов’язане - - Зв’яжіть користувача Discord із gateway. + + Прив’яжіть користувача Discord до Gateway. - - Груповий чат і поведінка списку дозволених. + + Поведінка групового чату та списку дозволених. - - Маршрутизуйте вхідні повідомлення до агентів. + + Спрямовуйте вхідні повідомлення до агентів. - + Модель загроз і посилення захисту. - - Зіставляйте guild і канали з агентами. + + Зіставляйте гільдії та канали з агентами. - + Поведінка нативних команд. diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 6c299d032..42dac7512 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,63 +1,63 @@ --- read_when: - - Ви створюєте плагін для OpenClaw - - Вам потрібно випустити схему конфігурації Plugin або налагодити помилки валідації Plugin -summary: Маніфест Plugin + вимоги до JSON-схеми (сувора перевірка конфігурації) + - Ви створюєте Plugin для OpenClaw + - Потрібно випустити схему конфігурації Plugin або діагностувати помилки валідації Plugin +summary: Вимоги до маніфесту Plugin + JSON-схеми (строга валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-29T23:17:38Z" + generated_at: "2026-04-30T00:56:13Z" model: gpt-5.5 provider: openai - source_hash: 4209b10042eaa88dca33073f3f5b8a024ee760bbe096fc2f476e12c2a874628e + source_hash: e71bc192e10504b59dbf587138cfeb3d53ef31e7cbe35d6a8f0672960d318e2d source_path: plugins/manifest.md workflow: 16 --- -Ця сторінка стосується лише **власного маніфесту 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 також автоматично виявляє ці макети пакетів, але вони не перевіряються за схемою `openclaw.plugin.json`, описаною тут. Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені корені skill, корені команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude і підтримувані набори хуків, коли структура відповідає -очікуванням середовища виконання OpenClaw. +типові значення LSP пакета Claude і підтримувані набори hooks, коли макет відповідає +очікуванням runtime OpenClaw. -Кожен власний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у +Кожен нативний Plugin OpenClaw **обов’язково** має постачати файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для перевірки конфігурації -**без виконання коду Plugin**. Відсутні або недійсні маніфести розглядаються як -помилки Plugin і блокують перевірку конфігурації. +**без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються +помилками Plugin і блокують перевірку конфігурації. -Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin). -Відомості про власну модель можливостей і поточні настанови щодо зовнішньої сумісності: +Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). +Для нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл `openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження вашого коду Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску -середовища виконання Plugin. +runtime Plugin. **Використовуйте його для:** - ідентичності Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь control plane -- скороченого визначення власника сімейства моделей +- метаданих автентифікації, onboarding і налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь control-plane +- скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих запуску QA, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації для конкретних каналів, об’єднаних із каталогом і поверхнями перевірки +- метаданих QA runner, які може перевіряти спільний host `openclaw qa` +- метаданих конфігурації для конкретних каналів, об’єднаних у каталог і поверхні перевірки -**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення точок входу коду +**Не використовуйте його для:** реєстрації runtime-поведінки, оголошення entrypoints коду або метаданих встановлення npm. Вони належать до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -152,75 +152,75 @@ OpenClaw також автоматично виявляє ці структур ## Довідник полів верхнього рівня -| Поле | Обов'язкове | Тип | Що це означає | -| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. Це контракт площини керування для майбутнього списку лише для читання, початкового налаштування, вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | -| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, якою володіє провайдер. Використовуйте її, щоб виключити локальних або самостійно розміщених провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | -| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів і префіксів ідентифікаторів моделей, яким володіє провайдер і яке має виконуватися до завантаження середовища виконання провайдера. | -| `providerEndpoints` | Ні | `object[]` | Метадані хоста або `baseUrl` кінцевої точки, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера. | -| `providerRequest` | Ні | `object` | Недорогі метадані сімейства провайдера та сумісності запитів, які використовує загальна політика запитів до завантаження середовища виконання провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів виведення CLI, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або бекенд CLI, для яких синтетичний auth hook, яким володіє Plugin, має перевірятися під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, якими володіє вбудований Plugin і які представляють несекретний локальний, OAuth або навколишній стан облікових даних. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні env-метадані для пошуку автентифікації та стану провайдера. Для нових Plugins надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом періоду застарівання. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, що спільно використовує базовий ключ API провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Недорогі env-метадані каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації на основі env, які мають бачити загальні помічники запуску та конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для засобів вибору під час початкового налаштування, визначення бажаного провайдера та простого підключення прапорців CLI. | -| `activation` | Ні | `object` | Недорогі метадані планувальника активації для запуску, провайдера, команди, каналу, маршруту та завантаження, спричиненого можливістю. Лише метадані; фактичною поведінкою все ще володіє середовище виконання Plugin. | -| `setup` | Ні | `object` | Недорогі дескриптори налаштування та початкового налаштування, які поверхні виявлення й налаштування можуть перевіряти без завантаження середовища виконання Plugin. | -| `qaRunners` | Ні | `object[]` | Недорогі дескриптори запуску QA, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх auth hooks, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Недорогі стандартні значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест і які об'єднуються з поверхнями виявлення та перевірки до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | -| `name` | Ні | `string` | Зручна для читання назва Plugin. | -| `description` | Ні | `string` | Короткий підсумок, що відображається на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | UI-мітки, заповнювачі та підказки щодо чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що означає | +| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту й використовуються для автоматичного завантаження Plugin перед runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього спискування лише для читання, онбордингу, вибирачів моделей, псевдонімів і придушення без завантаження runtime Plugin. | +| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, що належить провайдеру. Використовуйте її, щоб виключити локальних або самостійно розміщених провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | +| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів ідентифікаторів моделей, що належить провайдеру й має виконуватися до завантаження runtime провайдера. | +| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. | +| `providerRequest` | Ні | `object` | Легкі метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend інференсу CLI, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або CLI backend, для яких синтетичний auth hook, що належить Plugin, має перевірятися під час холодного виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw досі читає це під час періоду deprecation. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding provider, що спільно використовує API key та auth profiles базового провайдера. | +| `channelEnvVars` | Ні | `Record` | Легкі env-метадані каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації на основі env, які мають бачити загальні helper запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані вибору автентифікації для вибирачів онбордингу, визначення бажаного провайдера та простого підключення CLI flags. | +| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, спричиненого запуском, провайдером, командою, каналом, маршрутом і capability. Лише метадані; фактичною поведінкою досі володіє runtime Plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевірити без завантаження runtime Plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, що використовуються спільним host `openclaw qa` до завантаження runtime Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі стандартні значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються з поверхнями виявлення та перевірки до завантаження runtime. | +| `skills` | Ні | `string[]` | Директорії Skills для завантаження, відносні до кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | UI labels, placeholders і sensitivity hints для полів конфігурації. | -## Довідка providerAuthChoices +## Довідник providerAuthChoices -Кожен запис `providerAuthChoices` описує один вибір для початкового налаштування або автентифікації. -OpenClaw читає це до завантаження середовища виконання провайдера. +Кожен запис `providerAuthChoices` описує один вибір онбордингу або автентифікації. +OpenClaw читає це до завантаження runtime провайдера. Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти -налаштування, отримані з дескрипторів, і метадані інсталяційного каталогу без -завантаження середовища виконання провайдера. +налаштування, отримані з дескрипторів, і метадані install-catalog без завантаження +runtime провайдера. -| Поле | Обов’язкове | Тип | Що означає | -| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей вибір. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно спрямувати запит. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовують потоки onboarding і 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">` | У яких поверхнях onboarding має з’являтися цей вибір. Якщо пропущено, типовим значенням є `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей вибір. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно передати керування. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовують потоки onboarding і 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">` | Поверхні onboarding, на яких має з’являтися цей вибір. Якщо не вказано, типовим значенням є `["text-inference"]`. | -## Довідник commandAliases +## довідка commandAliases -Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково додати до `plugins.allow` або спробувати виконати як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. +Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть +помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. ```json { @@ -234,53 +234,53 @@ 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 -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane +Використовуйте `activation`, коли plugin може дешево оголосити, які події площини керування мають включати його до плану активації/завантаження. Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку середовища виконання, не замінює `register(...)` і не гарантує, що -код Plugin уже виконано. Планувальник активації використовує ці поля, щоб -звузити список кандидатних plugins перед поверненням до наявних метаданих -володіння маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і hooks. +код plugin уже виконано. Планувальник активації використовує ці поля, щоб +звузити список кандидатів plugin перед поверненням до наявних метаданих володіння маніфесту, +таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +`providers`, `channels`, `commandAliases`, дескриптори налаштування або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок -планувальника, які не можна представити цими полями володіння. -Використовуйте верхньорівневе `cliBackends` для псевдонімів середовища виконання CLI, як-от `claude-cli`, +планувальнику, які неможливо представити цими полями володіння. +Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для -вбудованих ідентифікаторів agent harness, які ще не мають поля володіння. +вбудованих ідентифікаторів агентних harness, які ще не мають поля володіння. -Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання й не -замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugins, тому -відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не має +Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання й не +замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому +відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не повинна змінювати коректність, доки ще існують застарілі резервні механізми володіння маніфесту. -Кожен Plugin має навмисно задавати `activation.onStartup`, оскільки OpenClaw відходить -від неявних імпортів під час запуску. Установлюйте його в `true` лише тоді, коли Plugin повинен -виконуватися під час запуску Gateway. Установлюйте його в `false`, коли Plugin інертний під час -запуску й має завантажуватися лише від вужчих тригерів. Якщо `onStartup` пропущено, зберігається -застарілий резервний механізм sidecar неявного запуску для plugins без -статичних метаданих можливостей; майбутні версії можуть припинити завантаження таких plugins під час запуску, -якщо вони не оголосять `activation.onStartup: true`. Звіти про стан і сумісність Plugin -попереджають `legacy-implicit-startup-sidecar`, коли Plugin -далі покладається на цей резервний механізм. +Кожен plugin має свідомо встановлювати `activation.onStartup`, оскільки OpenClaw відходить +від неявних імпортів під час запуску. Встановлюйте його в `true` лише тоді, коли plugin повинен +виконуватися під час запуску Gateway. Встановлюйте його в `false`, коли plugin інертний під час +запуску й має завантажуватися лише через вужчі тригери. Пропуск `onStartup` зберігає +застарілий резервний механізм неявного sidecar під час запуску для plugin без +статичних метаданих можливостей; майбутні версії можуть припинити завантажувати такі +plugin під час запуску, якщо вони не оголосять `activation.onStartup: true`. Звіти про стан і +сумісність plugin попереджають `legacy-implicit-startup-sidecar`, коли plugin +досі покладається на цей резервний механізм. Для тестування міграції встановіть `OPENCLAW_DISABLE_LEGACY_IMPLICIT_STARTUP_SIDECARS=1`, щоб вимкнути лише цей -застарілий резервний механізм. Цей режим opt-in не блокує явні -plugins з `activation.onStartup: true` або plugins, завантажені через channel, config, -agent-harness, memory чи інші вужчі тригери активації. +застарілий резервний механізм. Цей режим із явним увімкненням не блокує plugin з явним +`activation.onStartup: true` або plugin, завантажені каналом, конфігурацією, +agent-harness, пам’яттю чи іншими вужчими тригерами активації. ```json { @@ -296,45 +296,45 @@ agent-harness, memory чи інші вужчі тригери активації } ``` -| Поле | Обов’язкове | Тип | Що означає | -| ------------------ | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен Plugin має задавати це поле. `true` імпортує Plugin під час запуску; `false` відмовляється від застарілого неявного резервного запуску sidecar, якщо інший відповідний тригер не вимагає завантаження. | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте верхньорівневе `cliBackends` для псевдонімів бекендів CLI. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори channels, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Відносні до кореня шляхи config, які мають включати цей Plugin до планів запуску/завантаження, коли шлях наявний і явно не вимкнений. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовуються плануванням активації control plane. За можливості віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен plugin має встановлювати це поле. `true` імпортує plugin під час запуску; `false` відмовляється від застарілого неявного резервного запуску sidecar, якщо інший відповідний тригер не потребує завантаження. | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Використовуйте верхньорівневий `cliBackends` для псевдонімів backend CLI. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей plugin до планів запуску/завантаження, коли шлях наявний і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, які використовуються плануванням активації площини керування. Коли можливо, віддавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні live-споживачі: -- планування запуску Gateway використовує `activation.onStartup` для явного імпорту під час запуску - і відмови від застарілого неявного резервного запуску sidecar -- планування CLI, ініційоване командою, повертається до застарілих +- планування запуску Gateway використовує `activation.onStartup` для явного імпорту + під час запуску та відмови від застарілого неявного резервного запуску sidecar +- планування CLI, викликане командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harnesses і верхньорівневе `cliBackends[]` для псевдонімів середовища виконання CLI -- планування setup/channel, ініційоване channel, повертається до застарілого володіння `channels[]`, - коли явних метаданих активації channel немає -- планування plugins під час запуску використовує `activation.onConfigPaths` для кореневих - поверхонь config, не пов’язаних із channel, як-от блок `browser` у вбудованому browser Plugin -- планування setup/runtime, ініційоване провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явних метаданих - активації провайдера немає +- планування запуску середовища виконання агента використовує `activation.onAgentHarnesses` для + вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI +- планування налаштування/каналу, викликане каналом, повертається до застарілого володіння `channels[]`, + коли відсутні явні метадані активації каналу +- планування plugin під час запуску використовує `activation.onConfigPaths` для неканальних кореневих + поверхонь конфігурації, таких як блок `browser` вбудованого browser plugin +- планування налаштування/середовища виконання, викликане провайдером, повертається до застарілого володіння + `providers[]` і верхньорівневого `cliBackends[]`, коли відсутні явні метадані + активації провайдера Діагностика планувальника може відрізняти явні підказки активації від резервного володіння маніфесту. Наприклад, `activation-command-hint` означає, що -збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що +`activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста й тестів; автори Plugin мають і далі оголошувати метадані, +діагностики хоста й тестів; автори plugin мають і далі оголошувати метадані, які найкраще описують володіння. -## Довідник qaRunners +## довідка qaRunners -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runners під -спільним коренем `openclaw qa`. Залишайте ці метадані дешевими й статичними; середовище виконання Plugin -і далі володіє фактичною реєстрацією CLI через легку +Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner під +спільним коренем `openclaw qa`. Тримайте ці метадані дешевими та статичними; середовище +виконання plugin усе одно володіє фактичною реєстрацією CLI через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json @@ -348,15 +348,15 @@ agent-harness, memory чи інші вужчі тригери активації } ``` -| Поле | Обов’язково | Тип | Що означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------------ | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна команда-заглушка. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | -------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна заглушкова команда. | ## довідка setup -Використовуйте `setup`, коли поверхням налаштування та onboarding потрібні дешеві метадані, що належать plugin, -перед завантаженням runtime. +Використовуйте `setup`, коли поверхням налаштування й onboarding потрібні дешеві метадані, належні Plugin, +до завантаження runtime. ```json { @@ -384,83 +384,83 @@ agent-harness, memory чи інші вужчі тригери активації } ``` -Верхньорівневе `cliBackends` залишається чинним і надалі описує бекенди виведення CLI. -`setup.cliBackends` є специфічною для налаштування поверхнею дескрипторів для +Верхньорівневий `cliBackends` залишається чинним і продовжує описувати backend-и виведення CLI. +`setup.cliBackends` — це специфічна для setup поверхня дескрипторів для потоків control-plane/setup, які мають залишатися лише метаданими. -Коли наявні `setup.providers` і `setup.cliBackends`, вони є пріоритетною -поверхнею пошуку з підходом descriptor-first для виявлення налаштувань. Якщо дескриптор лише -звужує plugin-кандидат, а налаштуванню все ще потрібні багатші runtime-хуки на етапі налаштування, -встановіть `requiresRuntime: true` і залиште `setup-api` як +Коли вони наявні, `setup.providers` і `setup.cliBackends` є бажаною +поверхнею пошуку за принципом descriptor-first для виявлення setup. Якщо дескриптор лише +звужує кандидата Plugin, а setup все ще потребує багатших runtime-хуків часу setup, +задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації провайдера та -змінних середовища. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності -під час періоду вилучення, але непакетні plugins, які все ще його використовують, +OpenClaw також включає `setup.providers[].envVars` у загальні пошуки auth провайдера та +env-var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +протягом вікна застарівання, але небандловані plugins, які все ще його використовують, отримують діагностику маніфесту. Нові plugins мають розміщувати метадані env для setup/status у `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти налаштування з `setup.providers[].authMethods`, -коли запис налаштування недоступний або коли `setup.requiresRuntime: false` -оголошує, що runtime налаштування не потрібен. Явні записи `providerAuthChoices` залишаються -пріоритетними для власних міток, CLI-прапорів, області onboarding і метаданих асистента. +OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, +коли запис setup недоступний або коли `setup.requiresRuntime: false` +оголошує runtime setup непотрібним. Явні записи `providerAuthChoices` залишаються +бажаними для кастомних міток, прапорців CLI, області onboarding і метаданих асистента. -Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні налаштування. OpenClaw трактує явне `false` як контракт лише на дескрипторах -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку налаштування. Якщо -plugin лише з дескрипторами все ж постачає один із цих runtime-записів налаштування, -OpenClaw повідомляє додаткову діагностику й надалі ігнорує його. Пропущений +Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескрипторах +і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо +Plugin лише з дескрипторами все ще постачає один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущений `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали -дескриптори без прапора, не ламалися. +дескриптори без прапорця, не зламалися. -Оскільки пошук налаштування може виконувати код `setup-api`, що належить plugin, нормалізовані +Оскільки пошук setup може виконувати код `setup-api`, належний Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -виявлених plugins. Неоднозначне володіння завершується відмовою замість вибору -переможця за порядком виявлення. +виявлених plugins. Неоднозначне володіння завершується закрито, замість вибору +переможця з порядку виявлення. -Коли runtime налаштування виконується, діагностика реєстру налаштування повідомляє про дрейф дескрипторів, -якщо `setup-api` реєструє провайдера або CLI-бекенд, який дескриптори маніфесту +Коли runtime setup виконується, діагностика реєстру setup повідомляє про розбіжність дескрипторів, +якщо `setup-api` реєструє провайдера або backend CLI, які дескриптори маніфесту не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. -Ця діагностика є додатковою й не відхиляє застарілі plugins. +Ці діагностики є додатковими й не відхиляють застарілі plugins. ### довідка setup.providers -| Поле | Обов’язково | Тип | Що означає | -| -------------- | ----------- | ---------- | -------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id провайдера, відкритий під час setup або onboarding. Тримайте нормалізовані ids глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ids методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. | -| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів автентифікації для провайдерів, які можуть автентифікуватися через несекретні маркери. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | ID провайдера, доступний під час setup або onboarding. Тримайте нормалізовані ID глобально унікальними. | +| `authMethods` | Ні | `string[]` | ID методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | +| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів auth для провайдерів, які можуть автентифікуватися через несекретні маркери. | -`authEvidence` призначений для локальних маркерів облікових даних, що належать провайдеру та можуть бути -перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: -без мережевих викликів, без читання keychain або менеджера секретів, без команд shell і без -зондувань API провайдера. +`authEvidence` призначено для локальних маркерів облікових даних, належних провайдеру, які можна +перевірити без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: +без мережевих викликів, без читання keychain або secret-manager, без shell-команд і без +проб API провайдера. Підтримувані записи доказів: -| Поле | Обов’язково | Тип | Що означає | -| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------- | -| `type` | Так | `string` | Наразі `local-file-with-env`. | -| `fileEnvVar` | Ні | `string` | Змінна середовища, що містить явний шлях до файла облікових даних. | -| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, що перевіряються, коли `fileEnvVar` відсутній або порожній. Підтримує `${HOME}`. | -| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна зі вказаних змінних середовища має бути непорожньою, перш ніж доказ стане чинним. | -| `requiresAllEnv` | Ні | `string[]` | Кожна вказана змінна середовища має бути непорожньою, перш ніж доказ стане чинним. | -| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | -| `source` | Ні | `string` | Користувацька мітка джерела для виводу auth/status. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------- | +| `type` | Так | `string` | Наразі `local-file-with-env`. | +| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файлу облікових даних. | +| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | +| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна з перелічених env vars має бути непорожньою, перш ніж доказ стане чинним. | +| `requiresAllEnv` | Ні | `string[]` | Кожна перелічена env var має бути непорожньою, перш ніж доказ стане чинним. | +| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | +| `source` | Ні | `string` | Користувацька мітка джерела для виводу auth/status. | ### поля setup -| Поле | Обов’язково | Тип | Що означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------ | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, відкриті під час setup і onboarding. | -| `cliBackends` | Ні | `string[]` | Ids бекендів на етапі налаштування, що використовуються для пошуку setup з підходом descriptor-first. Тримайте нормалізовані ids глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ids міграцій конфігурації, що належать поверхні setup цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку дескрипторів. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup і onboarding. | +| `cliBackends` | Ні | `string[]` | ID backend-ів часу setup, що використовуються для пошуку setup за принципом descriptor-first. Тримайте нормалізовані ID глобально унікальними. | +| `configMigrations` | Ні | `string[]` | ID міграцій конфігурації, належні поверхні setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup все ще потребує виконання `setup-api` після пошуку дескрипторів. | ## довідка uiHints -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від назв полів конфігурації до малих підказок рендерингу. ```json { @@ -477,19 +477,19 @@ OpenClaw повідомляє додаткову діагностику й на Кожна підказка поля може містити: -| Поле | Тип | Що означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Користувацька мітка поля. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теги. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| Поле | Тип | Що це означає | +| ------------- | ---------- | ------------------------------------- | +| `label` | `string` | Користувацька мітка поля. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові UI-теги. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст заповнювача для полів форми. | ## довідка contracts -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -читати без імпорту runtime plugin. +Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може +читати без імпорту runtime Plugin. ```json { @@ -511,48 +511,48 @@ OpenClaw повідомляє додаткову діагностику й на } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: -| Поле | Тип | Що означає | -| -------------------------------- | ---------- | ----------------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ids фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Runtime ids, для яких пакетний plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ids провайдерів, чиїм hook зовнішнього профілю автентифікації володіє цей plugin. | -| `speechProviders` | `string[]` | Ids провайдерів мовлення, якими володіє цей plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ids провайдерів транскрипції в реальному часі, якими володіє цей plugin. | -| `realtimeVoiceProviders` | `string[]` | Ids провайдерів голосу в реальному часі, якими володіє цей plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ids провайдерів embedding пам’яті, якими володіє цей plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ids провайдерів розуміння медіа, якими володіє цей plugin. | -| `imageGenerationProviders` | `string[]` | Ids провайдерів генерації зображень, якими володіє цей plugin. | -| `videoGenerationProviders` | `string[]` | Ids провайдерів генерації відео, якими володіє цей plugin. | -| `webFetchProviders` | `string[]` | Ids провайдерів web-fetch, якими володіє цей plugin. | -| `webSearchProviders` | `string[]` | Ids провайдерів web-search, якими володіє цей plugin. | -| `migrationProviders` | `string[]` | Ids провайдерів імпорту, якими цей plugin володіє для `openclaw migrate`. | -| `tools` | `string[]` | Назви інструментів агента, якими цей plugin володіє для перевірок пакетних контрактів. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ---------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | ID фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Runtime ID, для яких бандлований Plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | ID провайдерів, чиїм хуком зовнішнього auth-профілю володіє цей Plugin. | +| `speechProviders` | `string[]` | ID провайдерів мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | ID провайдерів realtime-транскрипції, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | ID провайдерів realtime-голосу, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | ID провайдерів memory embedding, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | ID провайдерів media-understanding, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | ID провайдерів image-generation, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | ID провайдерів video-generation, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | ID провайдерів Web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | ID провайдерів Web-search, якими володіє цей Plugin. | +| `migrationProviders` | `string[]` | ID провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для бандлованих перевірок контрактів. | -`contracts.embeddedExtensionFactories` збережено для пакетних фабрик розширень, призначених лише для app-server Codex. -Пакетні перетворення результатів інструментів мають +`contracts.embeddedExtensionFactories` збережено для бандлованих фабрик розширень Codex, +призначених лише для app-server. Бандловані перетворення результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)` натомість. Зовнішні plugins не можуть -реєструвати middleware результатів інструментів, оскільки цей seam може переписувати високодовірений вивід інструментів +реєструвати middleware результатів інструментів, бо seam може переписувати високодовірений вивід інструментів до того, як модель його побачить. Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugins без оголошення все ще виконуються -через застарілий fallback сумісності, але цей fallback повільніший і -буде вилучений після міграційного вікна. +`contracts.externalAuthProviders`. Plugins без такого оголошення все ще запускаються +через застарілий резервний шлях сумісності, але цей резервний шлях повільніший і +буде вилучений після вікна міграції. -Пакетні провайдери memory embedding мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони відкривають, включно з -вбудованими адаптерами, такими як `local`. Автономні CLI-шляхи використовують цей контракт маніфесту, -щоб завантажувати лише plugin-власник до того, як повний runtime Gateway +Бандловані провайдери memory embedding мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ID адаптера, який вони надають, включно з +вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт +маніфесту, щоб завантажити лише Plugin-власник до того, як повний runtime Gateway зареєструє провайдерів. ## довідка mediaUnderstandingProviderMetadata -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має -моделі за замовчуванням, пріоритет fallback auto-auth або нативну підтримку документів, які -потрібні загальним core-помічникам до завантаження runtime. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли постачальник розуміння медіа має +моделі за замовчуванням, пріоритет резервного автоматичного автентифікування або нативну підтримку документів, які +потрібні загальним основним помічникам до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -576,26 +576,26 @@ Plugins провайдерів, які реалізують `resolveExternalAuth } ``` -Кожен запис провайдера може містити: +Кожен запис постачальника може містити: -| Поле | Тип | Що це означає | -| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові моделі для можливостей, які використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні документи, які підтримує провайдер. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей постачальник. | +| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору постачальника на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує постачальник. | -## Довідка щодо channelConfigs +## Довідник channelConfigs Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження середовища виконання. Налаштування каналу лише для читання або виявлення стану може використовувати ці метадані +завантаження середовища виконання. Виявлення налаштування/стану каналу лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний, або коли `setup.requiresRuntime: false` оголошує, що середовище виконання для налаштування не потрібне. `channelConfigs` — це метадані маніфесту Plugin, а не новий розділ конфігурації користувача верхнього рівня. Користувачі й надалі налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб визначити, якому Plugin належить цей налаштований -канал, до виконання коду середовища виконання Plugin. +OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим +каналом до виконання коду середовища виконання Plugin. Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: @@ -603,16 +603,16 @@ OpenClaw читає метадані маніфесту, щоб визначит - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` -Невбудовані плагіни, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw усе одно може завантажити плагін, але -схема конфігурації холодного шляху, налаштування та поверхні Control UI не можуть знати -форму параметрів, що належать каналу, доки не виконається runtime плагіна. +Невбудовані Plugins, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але +схема конфігурації холодного шляху, налаштування та поверхні Control UI не зможуть знати +форму параметрів, що належать каналу, доки не виконається середовище виконання Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок -конфігурації команд, які запускаються до завантаження runtime каналу. Вбудовані канали також можуть публікувати -ті самі типові значення через `package.json#openclaw.channel.commands` разом із -іншими метаданими каталогу каналів, що належать пакету. +`nativeSkillsAutoEnabled` можуть оголошувати статичні значення `auto` за замовчуванням для перевірок конфігурації команд, +які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати +такі самі значення за замовчуванням через `package.json#openclaw.channel.commands` разом +з іншими метаданими каталогу каналів, що належать пакету. ```json { @@ -645,20 +645,20 @@ OpenClaw читає метадані маніфесту, щоб визначит Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові UI-мітки/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору й інспектування, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | -| `commands` | `object` | Статичні автоматичні типові значення для нативних команд і нативних навичок у перевірках конфігурації до runtime. | -| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори плагінів, які цей канал має випереджати в поверхнях вибору. | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові підписи UI, заповнювачі та підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, що об’єднується з поверхнями вибору та інспектування, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | +| `commands` | `object` | Статичні значення автоматичного ввімкнення нативних команд і нативних Skills для перевірок конфігурації до середовища виконання. | +| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори Plugin, які цей канал має випереджати на поверхнях вибору. | -### Заміна іншого плагіна каналу +### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш плагін є бажаним власником для ідентифікатора каналу, який -також може надавати інший плагін. Поширені випадки: перейменований ідентифікатор плагіна, -самостійний плагін, що замінює вбудований плагін, або підтримуваний форк, який +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який +також може надавати інший Plugin. Типові випадки — перейменований ідентифікатор Plugin, +окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json @@ -680,22 +680,22 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор каналу, і -ідентифікатор бажаного плагіна. Якщо нижчопріоритетний плагін було вибрано лише тому, що +Коли `channels.chat` налаштовано, OpenClaw враховує і ідентифікатор каналу, і +ідентифікатор бажаного Plugin. Якщо Plugin нижчого пріоритету було вибрано лише тому, що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній -runtime-конфігурації, щоб один плагін володів каналом і його інструментами. Явний вибір користувача -все одно має пріоритет: якщо користувач явно вмикає обидва плагіни, OpenClaw -зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість того, щоб -непомітно змінювати запитаний набір плагінів. +конфігурації середовища виконання, щоб каналом і його інструментами володів один Plugin. Явний +вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugins, OpenClaw +зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість +мовчазної зміни запитаного набору Plugins. -Обмежуйте `preferOver` ідентифікаторами Plugin-ів, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. +Обмежуйте `preferOver` ідентифікаторами Plugins, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету, і воно не перейменовує ключі конфігурації користувача. -## Довідка щодо modelSupport +## Довідник modelSupport -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin постачальника за -скороченими ідентифікаторами моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до -завантаження середовища виконання Plugin-а. +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin постачальника з +коротких ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання +Plugin. ```json { @@ -710,23 +710,24 @@ OpenClaw застосовує такий порядок пріоритету: - явні посилання `provider/model` використовують метадані маніфесту `providers` власника - `modelPatterns` мають перевагу над `modelPrefixes` -- якщо збігаються і один невбудований Plugin, і один вбудований Plugin, перемагає - невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже постачальника +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть постачальника Поля: | Поле | Тип | Що це означає | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела регулярних виразів, які зіставляються зі скороченими ідентифікаторами моделей після вилучення суфікса профілю. | +| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` із короткими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела регулярних виразів, які зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю. | -## Довідка щодо modelCatalog +## Довідник modelCatalog Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей постачальника до -завантаження середовища виконання Plugin-а. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, -псевдонімів постачальників, правил приглушення та режиму виявлення. Оновлення під час виконання -далі належить коду середовища виконання постачальника, але маніфест повідомляє ядру, коли потрібне середовище виконання. +завантаження середовища виконання Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, +псевдонімів постачальників, правил пригнічення та режиму виявлення. Оновлення середовища виконання +й надалі належить коду середовища виконання постачальника, але маніфест повідомляє core, коли середовище виконання +потрібне. ```json { @@ -779,21 +780,21 @@ OpenClaw застосовує такий порядок пріоритету: | Поле | Тип | Що це означає | | -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів постачальників, що належать цьому Plugin-у. Ключі також мають з’являтися в `providers` верхнього рівня. | -| `aliases` | `Record` | Псевдоніми постачальників, які мають розв’язуватися до належного постачальника для планування каталогу або приглушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для постачальника. | -| `discovery` | `Record` | Чи можна читати каталог постачальника з метаданих маніфесту, оновлювати його в кеші, чи потрібне середовище виконання. | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів постачальників, що належать цьому Plugin. Ключі також мають бути присутні в `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми постачальників, які мають розв’язуватися у власного постачальника для планування каталогу або пригнічення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin пригнічує з причини, специфічної для постачальника. | +| `discovery` | `Record` | Чи можна читати каталог постачальника з метаданих маніфесту, оновлювати його в кеш або чи він потребує середовища виконання. | `aliases` бере участь у пошуку власника постачальника для планування каталогу моделей. -Цілі псевдонімів мають бути постачальниками верхнього рівня, що належать тому самому Plugin-у. Коли +Цілі псевдонімів мають бути постачальниками верхнього рівня, що належать тому самому Plugin. Коли список, відфільтрований за постачальником, використовує псевдонім, OpenClaw може прочитати маніфест власника та застосувати перевизначення API/базової URL-адреси псевдоніма без завантаження середовища виконання постачальника. Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки канонічного постачальника-власника. `suppressions` замінює старий хук середовища виконання постачальника `suppressBuiltInModel`. -Записи приглушення враховуються лише тоді, коли постачальник належить Plugin-у або -оголошений як ключ `modelCatalog.aliases`, що вказує на належного постачальника. Хуки приглушення +Записи пригнічення враховуються лише тоді, коли постачальник належить Plugin або +оголошений як ключ `modelCatalog.aliases`, що вказує на власного постачальника. Хуки пригнічення середовища виконання більше не викликаються під час розв’язання моделей. Поля постачальника: @@ -809,39 +810,39 @@ OpenClaw застосовує такий порядок пріоритету: | Поле | Тип | Що це означає | | --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі, без префікса `provider/`. | -| `name` | `string` | Необов’язкова показувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення базового URL для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов'язкова відображувана назва. | +| `api` | `ModelApi` | Необов'язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов'язкове перевизначення базової URL-адреси для окремої моделі. | +| `headers` | `Record` | Необов'язкові статичні заголовки для окремої моделі. | | `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи модель надає поведінку reasoning. | -| `contextWindow` | `number` | Нативне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження runtime-контексту, якщо воно відрізняється від `contextWindow`. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Власне контекстне вікно провайдера. | +| `contextTokens` | `number` | Необов'язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | | `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | -| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Пригнічуйте лише тоді, коли рядок узагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від available. | -| `replaces` | `string[]` | Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору та фільтри. | +| `cost` | `object` | Необов'язкова ціна в USD за мільйон токенів, включно з необов'язковим `tieredPricing`. | +| `compat` | `object` | Необов'язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Стан у списку. Приховуйте лише тоді, коли рядок взагалі не має з'являтися. | +| `statusReason` | `string` | Необов'язкова причина, показана зі станом, відмінним від доступного. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору й фільтри. | Поля пригнічення: | Поле | Тип | Що це означає | | -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно пригнітити. Має належати цьому plugin або бути оголошеним як власний alias. | +| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який потрібно пригнітити. Має належати цьому плагіну або бути оголошеним як власний псевдонім. | | `model` | `string` | Локальний для провайдера ідентифікатор моделі, який потрібно пригнітити. | -| `reason` | `string` | Необов’язкове повідомлення, що показується, коли пригнічений рядок запитують напряму. | -| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базових URL провайдера, потрібних для застосування пригнічення. | -| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` у конфігурації провайдера, потрібних для застосування пригнічення. | +| `reason` | `string` | Необов'язкове повідомлення, показане, коли пригнічений рядок запитують напряму. | +| `when.baseUrlHosts` | `string[]` | Необов'язковий список ефективних хостів базової URL-адреси провайдера, потрібних перед застосуванням пригнічення. | +| `when.providerConfigApiIn` | `string[]` | Необов'язковий список точних значень `api` з конфігурації провайдера, потрібних перед застосуванням пригнічення. | -Не розміщуйте дані, призначені лише для runtime, у `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку й вибору, відфільтровані за провайдером, могли пропустити виявлення через registry/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але refresh/cache може додати більше рядків пізніше; refreshable-рядки самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб дізнатися список. +Не розміщуйте дані лише часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку, відфільтрованого за провайдером, і засоби вибору могли пропустити виявлення через registry/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні як початкові або додаткові елементи списку, але оновлення/кеш може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити runtime провайдера, щоб знати список. -## Довідник modelIdNormalization +## Довідка `modelIdNormalization` -Використовуйте `modelIdNormalization` для дешевого очищення належних провайдеру ідентифікаторів моделей, яке має відбутися до завантаження runtime провайдера. Це тримає aliases, такі як короткі назви моделей, локальні для провайдера legacy-ідентифікатори та правила proxy-префіксів, у маніфесті власного plugin, а не в таблицях вибору моделей core. +Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, яким володіє провайдер, що має відбутися до завантаження runtime провайдера. Це тримає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті власного плагіна, а не в таблицях вибору моделей ядра. ```json { @@ -863,31 +864,31 @@ OpenClaw застосовує такий порядок пріоритету: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------- | -| `aliases` | `Record` | Точні aliases ідентифікаторів моделей без урахування регістру. Значення повертаються як записано. | -| `stripPrefixes` | `string[]` | Префікси, які потрібно видалити перед пошуком alias, корисно для legacy-дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса для bare-id після пошуку alias, ключовані за `modelPrefix` і `prefix`. | +| Поле | Тип | Що це означає | +| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- | +| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | +| `stripPrefixes` | `string[]` | Префікси, які потрібно вилучити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | +| `prefixWhenBare` | `string` | Префікс, який потрібно додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса для bare-id після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | -## Довідник providerEndpoints +## Довідка `providerEndpoints` -Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Core і далі володіє значенням кожного `endpointClass`; маніфести plugin володіють метаданими host і base URL. +Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Ядро все ще володіє значенням кожного `endpointClass`; маніфести плагінів володіють метаданими хоста та базової URL-адреси. Поля endpoint: -| Поле | Тип | Що це означає | -| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | Відомий core-клас endpoint, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, що відповідають класу endpoint. | -| `hostSuffixes` | `string[]` | Суфікси хостів, що відповідають класу endpoint. Додавайте префікс `.` для збігу лише за суфіксом домену. | -| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL, що відповідають класу endpoint. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно видалити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | +| Поле | Тип | Що це означає | +| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | Відомий клас endpoint ядра, як-от `openrouter`, `moonshot-native` або `google-vertex`. | +| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом endpoint. | +| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом endpoint. Починайте з `.` для зіставлення лише суфікса домену. | +| `baseUrls` | `string[]` | Точні нормалізовані базові URL-адреси HTTP(S), які зіставляються з класом endpoint. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | -## Довідник providerRequest +## Довідка `providerRequest` -Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, які потрібні загальній політиці запитів без завантаження runtime провайдера. Залишайте специфічне для поведінки переписування payload у runtime hooks провайдера або спільних допоміжних засобах provider-family. +Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Тримайте специфічне для поведінки переписування payload у runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів. ```json { @@ -910,12 +911,12 @@ OpenClaw застосовує такий порядок пріоритету: | Поле | Тип | Що це означає | | --------------------- | ------------ | ------------------------------------------------------------------------------------- | | `family` | `string` | Мітка сімейства провайдера, яку використовують загальні рішення сумісності запитів і діагностика. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий bucket сумісності provider-family для спільних допоміжних засобів запитів. | -| `openAICompletions` | `object` | Прапорці OpenAI-сумісних completions-запитів, наразі `supportsStreamingUsage`. | +| `compatibilityFamily` | `"moonshot"` | Необов'язковий кошик сумісності сімейства провайдерів для спільних допоміжних засобів запитів. | +| `openAICompletions` | `object` | Прапорці OpenAI-сумісних completion-запитів, наразі `supportsStreamingUsage`. | -## Довідник modelPricing +## Довідка `modelPricing` -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка pricing на control plane до завантаження runtime. Pricing cache Gateway читає ці метадані без імпорту runtime-коду провайдера. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш цін Gateway читає ці метадані без імпорту коду runtime провайдера. ```json { @@ -938,68 +939,68 @@ OpenClaw застосовує такий порядок пріоритету: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------ | ----------------- | --------------------------------------------------------------------------------------------------- | +| Поле | Тип | Що це означає | +| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | | `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Мапінг пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Мапінг пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що це означає | -| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ | +| Поле | Тип | Що це означає | +| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядайте ідентифікатори моделей зі slash як вкладені посилання provider/model, корисно для proxy-провайдерів, таких як OpenRouter. | -| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує dotted version ids на кшталт `claude-opus-4.6`. | +| `passthroughProviderModel` | `boolean` | Розглядайте ідентифікатори моделей зі скісною рискою як вкладені посилання provider/model; корисно для проксі-провайдерів, як-от OpenRouter. | +| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw — це preview-метадані, що належать OpenClaw, для провайдерів, plugins яких можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом установлених plugins. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні вибору installable-provider і pre-install моделей використовуватимуть, коли plugin провайдера не встановлено. +Індекс провайдерів OpenClaw - це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї плагіни ще можуть бути не встановлені. Він не є частиною маніфесту плагіна. Маніфести плагінів залишаються авторитетним джерелом установлених плагінів. Індекс провайдерів - це внутрішній fallback-контракт, який майбутні поверхні installable-provider і pre-install засобу вибору моделей використовуватимуть, коли плагін провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. `modelCatalog` маніфесту встановленого plugin. -3. Кеш каталогу моделей після явного refresh. +2. `modelCatalog` маніфесту встановленого плагіна. +3. Кеш каталогу моделей після явного оновлення. 4. Preview-рядки Індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секретів, увімкненого стану, runtime-хуків або -живих даних моделей, специфічних для облікового запису. Його каталоги попереднього перегляду використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести plugin, але мають залишатися обмеженими -стабільними метаданими відображення, якщо поля runtime-адаптера, як-от `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно синхронізованими з -маніфестом установленого plugin. Провайдери з живим виявленням `/models` мають +Індекс провайдерів не має містити секрети, увімкнений стан, runtime hooks або +актуальні дані моделей, специфічні для облікового запису. Його каталоги попереднього перегляду використовують ту саму форму рядка провайдера +`modelCatalog`, що й маніфести plugin, але мають залишатися обмеженими +стабільними відображуваними метаданими, якщо поля runtime-адаптера, як-от `api`, +`baseUrl`, ціни або прапорці сумісності, навмисно не підтримуються узгодженими з +маніфестом установленого plugin. Провайдери з актуальним виявленням `/models` мають записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати -звичайний список або onboarding викликати API провайдера. +звичайний listing чи onboarding викликати API провайдера. -Записи Індексу провайдерів також можуть містити метадані інстальованого plugin для провайдерів, -чий plugin переміщено з core або який інакше ще не встановлено. Ці -метадані віддзеркалюють шаблон каталогу каналів: назви пакета, npm install spec, -очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати -інстальований варіант налаштування. Після встановлення plugin перемагає його маніфест, а +Записи Індексу провайдерів також можуть містити метадані installable-plugin для провайдерів, +чий plugin було винесено з core або який інакше ще не встановлено. Ці +метадані віддзеркалюють шаблон каталогу каналів: назви package, npm install spec, +очікувана integrity та дешеві мітки вибору auth достатні, щоб показати +варіант installable setup. Після встановлення plugin його маніфест має пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі ключі можливостей верхнього рівня вважаються застарілими. Використовуйте `openclaw doctor --fix`, щоб +Застарілі capability keys верхнього рівня вважаються застарілими. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння -можливостями. +`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне +завантаження маніфесту більше не розглядає ці поля верхнього рівня як ownership +capability. -## Маніфест і package.json +## Маніфест проти package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | npm-метадані, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, налаштування або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, перевірка config, метадані вибору auth і підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | метадані npm, встановлення dependency та блок `openclaw`, що використовується для entrypoints, install gating, setup або метаданих catalog | -Якщо ви не впевнені, де мають бути певні метадані, скористайтеся цим правилом: +Якщо ви не впевнені, де має бути певний фрагмент метаданих, скористайтеся цим правилом: - якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки npm install, помістіть це в `package.json` +- якщо це стосується packaging, entry files або поведінки npm install, помістіть це в `package.json` ### Поля package.json, що впливають на виявлення @@ -1010,61 +1011,62 @@ OpenClaw застосовує такий порядок пріоритету: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує native-точки входу plugin. Має залишатися всередині каталогу пакета plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime-точки входу для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. | -| `openclaw.setupEntry` | Легка setup-only точка входу, що використовується під час onboarding, відкладеного запуску каналу та read-only статусу каналу/виявлення SecretRef. Має залишатися всередині каталогу пакета plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібрану JavaScript setup-точку входу для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. | -| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст вибору. | -| `openclaw.channel.commands` | Статичні native-команди та метадані native skill auto-default, що використовуються поверхнями конфігурації, аудиту та списку команд до завантаження runtime каналу. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти «чи вже існує env-only налаштування?» без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти «чи вже є щось із виконаним входом?» без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugins. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням semver-нижньої межі на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled-plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу setup-only поверхням каналів завантажуватися перед повним plugin каналу під час запуску. | +| `openclaw.extensions` | Оголошує native entrypoints plugin. Має залишатися всередині директорії package plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoints для встановлених packages. Має залишатися всередині директорії package plugin. | +| `openclaw.setupEntry` | Легковагий setup-only entrypoint, що використовується під час onboarding, відкладеного запуску каналів і read-only status каналу/виявлення SecretRef. Має залишатися всередині директорії package plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript setup entrypoint для встановлених packages. Має залишатися всередині директорії package plugin. | +| `openclaw.channel` | Дешеві метадані catalog каналу, як-от мітки, шляхи docs, aliases і текст вибору. | +| `openclaw.channel.commands` | Статичні метадані native command і native skill auto-default, що використовуються config, audit і поверхнями списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легковагі метадані configured-state checker, які можуть відповісти "чи вже існує env-only setup?" без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легковагі метадані persisted-auth checker, які можуть відповісти "чи вже хтось увійшов?" без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки install/update для bundled і зовнішньо опублікованих plugins. | +| `openclaw.install.defaultChoice` | Бажаний шлях install, коли доступно кілька install sources. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія host OpenClaw, із semver floor на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок npm dist integrity, як-от `sha512-...`; потоки install і update перевіряють отриманий artifact за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення reinstall bundled-plugin, коли config недійсний. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє setup-only поверхням каналу завантажуватися перед повним plugin каналу під час startup. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в +Метадані маніфесту визначають, які варіанти provider/channel/setup з'являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє onboarding, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих -варіантів. Не переміщуйте підказки встановлення в `openclaw.plugin.json`. +варіантів. Не переносіть підказки install у `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження -реєстру маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають -plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час install і завантаження +registry маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають +plugin на старіших hosts. -Точне закріплення npm-версії вже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні specs з `expectedIntegrity`, щоб потоки оновлення завершувалися -закрито, якщо отриманий npm-артефакт більше не відповідає закріпленому випуску. -Інтерактивний onboarding досі пропонує довірені registry npm specs, зокрема голі -назви пакетів і dist-tags, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, integrity-pinned, missing-integrity, package-name -mismatch і invalid default-choice джерела. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає дійсного npm-джерела, яке він може закріпити. -Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення застосовують його; коли його пропущено, registry resolution +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи external catalog +мають поєднувати точні specs з `expectedIntegrity`, щоб потоки update завершувалися +fail closed, якщо отриманий npm artifact більше не відповідає закріпленому release. +Interactive onboarding усе ще пропонує довірені registry npm specs, включно з bare +package names і dist-tags, для сумісності. Діагностика catalog може +розрізняти exact, floating, integrity-pinned, missing-integrity, package-name +mismatch і invalid default-choice sources. Вона також попереджає, коли +`expectedIntegrity` наявний, але немає дійсного npm source, який він може закріпити. +Коли `expectedIntegrity` наявний, +потоки install/update примусово його застосовують; коли його пропущено, registry resolution записується без integrity pin. -Channel plugins мають надавати `openclaw.setupEntry`, коли сканування статусу, списку каналів -або SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного -runtime. Setup entry має надавати метадані каналу разом із setup-safe адаптерами конфігурації, -статусу та секретів; тримайте мережеві клієнти, gateway listeners і -transport runtimes в основній точці входу extension. +Plugins каналів мають надавати `openclaw.setupEntry`, коли status, список каналів +або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного +runtime. Setup entry має надавати метадані каналу плюс setup-safe config, +status і secrets adapters; тримайте network clients, Gateway listeners і +transport runtimes в основному entrypoint extension. -Поля runtime-точок входу не перевизначають перевірки меж пакета для полів source-точок -входу. Наприклад, `openclaw.runtimeExtensions` не може зробити шлях -`openclaw.extensions`, що виходить за межі, придатним до завантаження. +Поля runtime entrypoint не перевизначають перевірки меж package для полів source +entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити +escaping шлях `openclaw.extensions` придатним до завантаження. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не -робить довільні зламані конфігурації придатними для встановлення. Нині він дозволяє потокам -встановлення відновлюватися лише після конкретних застарілих помилок оновлення bundled-plugin, як-от -відсутній шлях bundled plugin або застарілий запис `channels.` для того самого -bundled plugin. Непов’язані помилки конфігурації все ще блокують встановлення й спрямовують операторів +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить +довільні broken configs installable. Наразі він лише дозволяє потокам install +відновлюватися після конкретних stale bundled-plugin upgrade failures, як-от +відсутній шлях bundled plugin або stale запис `channels.` для того самого +bundled plugin. Непов'язані помилки config усе ще блокують install і спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного checker-модуля: +`openclaw.channel.persistedAuthState` — це package metadata для крихітного checker +module: ```json { @@ -1080,12 +1082,12 @@ bundled plugin. Непов’язані помилки конфігурації } ``` -Використовуйте це, коли потокам setup, doctor, status або read-only presence потрібна дешева -yes/no auth probe до завантаження повного plugin каналу. Persisted auth state — це -не configured channel state: не використовуйте ці метадані для автоматичного ввімкнення plugins, -відновлення runtime-залежностей або рішення, чи має завантажуватися runtime каналу. +Використовуйте це, коли setup, doctor, status або read-only presence flows потребують дешевого +yes/no auth probe до завантаження повного plugin каналу. Persisted auth state не є +configured channel state: не використовуйте ці метадані для auto-enable plugins, +repair runtime dependencies або визначення, чи має завантажуватися runtime каналу. Цільовий export має бути невеликою функцією, яка читає лише persisted state; не -спрямовуйте його через повний runtime barrel каналу. +спрямовуйте її через повний runtime barrel каналу. `openclaw.channel.configuredState` має таку саму форму для дешевих env-only configured checks: @@ -1104,33 +1106,33 @@ configured checks: } ``` -Використовуйте це, коли канал може визначити configured-state з env або інших крихітних -non-runtime вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або справжнього -runtime каналу, залиште цю логіку в hook plugin `config.hasConfiguredState` -натомість. +Використовуйте це, коли канал може відповісти про configured-state з env або інших малих +non-runtime inputs. Якщо перевірці потрібні full config resolution або реальний +runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` +plugin. -## Пріоритет виявлення (повторювані id plugin) +## Пріоритет виявлення (повторювані plugin ids) -OpenClaw виявляє plugins із кількох коренів (bundled, global install, workspace, explicit config-selected paths). Якщо два результати виявлення мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє plugins із кількох roots (bundled, global install, workspace, explicit config-selected paths). Якщо два виявлення мають однаковий `id`, зберігається лише **найвищопріоритетніший** маніфест; duplicates з нижчим пріоритетом відкидаються замість завантаження поруч із ним. Пріоритет, від найвищого до найнижчого: 1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` 2. **Bundled** — plugins, що постачаються з OpenClaw -3. **Global install** — plugins, установлені в глобальний корінь plugins OpenClaw +3. **Global install** — plugins, установлені в глобальний root plugins OpenClaw 4. **Workspace** — plugins, виявлені відносно поточного workspace Наслідки: -- Forked або застаріла копія bundled plugin у workspace не затінить bundled-збірку. -- Щоб справді перевизначити bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на workspace discovery. -- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Forked або stale копія bundled plugin у workspace не shadow bundled build. +- Щоб справді override bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на workspace discovery. +- Duplicate drops логуються, щоб Doctor і startup diagnostics могли вказати на discarded copy. ## Вимоги JSON Schema -- **Кожен plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. +- **Кожен plugin має постачати JSON Schema**, навіть якщо він не приймає config. +- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Schemas перевіряються під час читання/запису config, а не під час runtime. ## Поведінка перевірки @@ -1138,33 +1140,33 @@ OpenClaw виявляє plugins із кількох коренів (bundled, glo маніфесті плагіна. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` мають посилатися на **доступні для виявлення** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**. -- Якщо плагін установлено, але його маніфест або схема пошкоджені чи відсутні, +- Якщо плагін встановлено, але його маніфест або схема пошкоджені чи відсутні, перевірка не проходить, а Doctor повідомляє про помилку плагіна. - Якщо конфігурація плагіна існує, але плагін **вимкнено**, конфігурація зберігається, а - **попередження** відображається в Doctor + журналах. + **попередження** відображається в Doctor і журналах. -Див. [Довідник із конфігурації](/uk/gateway/configuration), щоб переглянути повну схему `plugins.*`. +Повну схему `plugins.*` див. у [довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест є **обов'язковим для нативних плагінів OpenClaw**, зокрема для завантажень із локальної файлової системи. Середовище виконання все одно завантажує модуль плагіна окремо; маніфест потрібен лише для виявлення + перевірки. -- Нативні маніфести аналізуються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все ще є об'єктом. -- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо вони не потрібні плагіну. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). -- Оголошуйте ексклюзивний тип плагіна в цьому маніфесті. `OpenClawPluginDefinition.kind` у точці входу середовища виконання застарів і залишається лише як резервна сумісність для старіших плагінів. -- Метадані змінних середовища (`setup.providers[].envVars`, застарілі `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставлення Cron та інші поверхні лише для читання все ще застосовують політику довіри до плагіна й ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих майстра середовища виконання, які потребують коду провайдера, див. [Хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до списку дозволів менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для нативних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime все одно завантажує модуль плагіна окремо; маніфест потрібен лише для виявлення й перевірки. +- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок приймаються, якщо підсумкове значення все ще є об’єктом. +- Завантажувач маніфестів читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна опустити, якщо плагіну вони не потрібні. +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати великий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Оголошуйте ексклюзивний тип плагіна в цьому маніфесті. Runtime-поле `OpenClawPluginDefinition.kind` застаріло й залишається лише як резервна сумісність для старіших плагінів. +- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) мають лише декларативний характер. Статус, аудит, перевірка доставлення Cron та інші поверхні лише для читання все ще застосовують довіру до плагіна й політику фактичної активації, перш ніж вважати змінну середовища налаштованою. +- Для метаданих runtime-майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). -## Пов'язане +## Пов’язане Початок роботи з плагінами. - + Внутрішня архітектура та модель можливостей.