From ef885f7c54200d77e463bcf17686e9da2abb8cc3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 01:37:36 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/discord.md | 539 +++++++++++++-------------- docs/uk/channels/mattermost.md | 240 ++++++------ docs/uk/channels/slack.md | 326 ++++++++--------- docs/uk/concepts/streaming.md | 178 ++++----- docs/uk/plugins/sdk-migration.md | 375 ++++++++++--------- docs/uk/plugins/sdk-overview.md | 603 +++++++++++++++---------------- 6 files changed, 1134 insertions(+), 1127 deletions(-) diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 8fd26c9a9..4c8e1d8e4 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,36 +1,36 @@ --- read_when: - - Робота над функціями каналу Discord -summary: Статус підтримки бота Discord, можливості та налаштування + - Працюю над функціями каналу Discord +summary: Статус підтримки бота Discord, можливості та конфігурація title: Discord x-i18n: - generated_at: "2026-04-21T16:52:59Z" + generated_at: "2026-04-22T01:34:39Z" model: gpt-5.4 provider: openai - source_hash: 1681315a6c246c4b68347f5e22319e132f30ea4e29a19e7d1da9e83dce7b68d0 + source_hash: 613ae39bc4b8c5661cbaab4f70a57af584f296581c3ce54ddaef0feab44e7e42 source_path: channels/discord.md workflow: 15 --- # Discord (Bot API) -Статус: готово для приватних повідомлень і каналів серверів через офіційний шлюз Discord. +Статус: готово для приватних повідомлень і каналів гільдій через офіційний шлюз Discord. - - Для приватних повідомлень Discord типовим режимом є режим підключення. + + Для приватних повідомлень Discord типово використовується режим зіставлення. - Власна поведінка команд і каталог команд. + Нативна поведінка команд і каталог команд. - + Міжканальна діагностика та процес відновлення. ## Швидке налаштування -Вам потрібно буде створити новий застосунок із ботом, додати бота на свій сервер і підключити його до 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**). @@ -40,12 +40,12 @@ x-i18n: - - Перебуваючи на сторінці **Bot**, прокрутіть униз до **Privileged Gateway Intents** і увімкніть: + + На сторінці **Bot** прокрутіть вниз до **Privileged Gateway Intents** і ввімкніть: - **Message Content Intent** (обов’язково) - - **Server Members Intent** (рекомендовано; обов’язково для allowlist ролей і зіставлення імен із ID) - - **Presence Intent** (необов’язково; потрібне лише для оновлень статусу присутності) + - **Server Members Intent** (рекомендовано; обов’язково для allowlist ролей і зіставлення імен з ID) + - **Presence Intent** (необов’язково; потрібне лише для оновлень статусу) @@ -56,14 +56,14 @@ x-i18n: Попри назву, це генерує ваш перший токен — нічого не «скидається». - Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він незабаром знадобиться. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він скоро знадобиться. - + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL-запрошення з правильними дозволами, щоб додати бота на свій сервер. - Прокрутіть униз до **OAuth2 URL Generator** і ввімкніть: + Прокрутіть вниз до **OAuth2 URL Generator** і ввімкніть: - `bot` - `applications.commands` @@ -77,30 +77,30 @@ x-i18n: - Attach Files - Add Reactions (необов’язково) - Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте побачити свого бота на сервері Discord. + Скопіюйте згенерований URL унизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте побачити свого бота на сервері Discord. - - Повернувшись у застосунок Discord, вам потрібно ввімкнути режим розробника, щоб мати змогу копіювати внутрішні ID. + + Повернувшись у застосунок Discord, вам потрібно ввімкнути режим розробника, щоб можна було копіювати внутрішні ID. 1. Натисніть **User Settings** (значок шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** - 2. Клацніть правою кнопкою миші на **значку сервера** на бічній панелі → **Copy Server ID** - 3. Клацніть правою кнопкою миші на **своєму аватарі** → **Copy User ID** + 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 має дозволяти вашому боту надсилати вам приватні повідомлення. Клацніть правою кнопкою миші значок свого **сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (включно з ботами) надсилати вам приватні повідомлення. Залишайте це ввімкненим, якщо хочете використовувати приватні повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали сервера, можете вимкнути приватні повідомлення після підключення. + Це дозволяє учасникам сервера (включно з ботами) надсилати вам приватні повідомлення. Залишайте цю опцію ввімкненою, якщо хочете використовувати приватні повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, після зіставлення можна вимкнути приватні повідомлення. - - Токен вашого бота Discord є секретом (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати своєму агенту. + + Токен вашого бота Discord — це секрет (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати своєму агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,17 +110,17 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши та знову запустивши процес `openclaw gateway run`. + Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й знову запустивши процес `openclaw gateway run`. - + - - Поговоріть зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, натомість скористайтеся вкладкою CLI / config. + + Напишіть своєму агенту OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому це. Якщо Discord — ваш перший канал, натомість використайте вкладку CLI / config. - > "Я вже задав токен свого Discord-бота в конфігурації. Будь ласка, заверши налаштування Discord із User ID `` і Server ID ``." + > "Я вже задав токен свого бота Discord у config. Будь ласка, заверши налаштування Discord з User ID `` і Server ID ``." Якщо ви віддаєте перевагу файловій конфігурації, задайте: @@ -146,21 +146,21 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Підтримуються відкриті значення `token`. Для `channels.discord.token` також підтримуються значення SecretRef у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Підтримуються відкриті значення `token`. Також для `channels.discord.token` підтримуються значення SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). - - Дочекайтеся, поки шлюз запуститься, а потім напишіть своєму боту в Discord у приватні повідомлення. Він відповість кодом підключення. + + Дочекайтеся, поки шлюз запуститься, а потім надішліть боту приватне повідомлення в Discord. Він відповість кодом зіставлення. - - Надішліть код підключення своєму агенту у вашому наявному каналі: + + Надішліть код зіставлення своєму агенту в наявному каналі: - > "Підтвердь цей код підключення Discord: ``" + > "Підтвердь цей код зіставлення Discord: ``" @@ -172,7 +172,7 @@ openclaw pairing approve discord - Термін дії кодів підключення спливає через 1 годину. + Термін дії кодів зіставлення спливає через 1 годину. Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через приватні повідомлення. @@ -180,23 +180,23 @@ openclaw pairing approve discord -Визначення токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервним значенням env. `DISCORD_BOT_TOKEN` використовується лише для типового облікового запису. -Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` використовується для цього конкретного виклику. Це стосується дій надсилання та читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису/параметри повторних спроб, як і раніше, беруться з вибраного облікового запису в активному знімку середовища виконання. +Визначення токена враховує обліковий запис. Значення токена в config мають пріоритет над резервним значенням env. `DISCORD_BOT_TOKEN` використовується лише для типового облікового запису. +Для розширених вихідних викликів (message tool/channel actions) явний `token` використовується для цього виклику. Це стосується дій надсилання та дій читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Налаштування політики облікового запису/повторних спроб і надалі беруться з вибраного облікового запису в активному знімку runtime. -## Рекомендовано: налаштуйте робочий простір сервера +## Рекомендовано: налаштуйте простір роботи гільдії -Коли приватні повідомлення вже працюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента зі своїм контекстом. Це рекомендовано для приватних серверів, де єте лише ви й ваш бот. +Щойно приватні повідомлення запрацюють, ви можете налаштувати свій сервер Discord як повноцінний простір роботи, де кожен канал матиме власну сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де єте тільки ви та ваш бот. - - Це дає змогу вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в приватних повідомленнях. + + Це дозволяє вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в приватних повідомленнях. - - > "Додай мій Discord Server ID `` до allowlist серверів" + + > "Додай мій Server ID Discord `` до allowlist гільдій" - + ```json5 { @@ -220,14 +220,14 @@ openclaw pairing approve discord - Типово ваш агент відповідає в каналах сервера лише тоді, коли його згадано через @mention. Для приватного сервера вам, імовірно, варто дозволити йому відповідати на кожне повідомлення. + Типово ваш агент відповідає в каналах гільдії лише тоді, коли його згадують через @mention. Для приватного сервера вам, імовірно, потрібно, щоб він відповідав на кожне повідомлення. - - > "Дозволь моєму агенту відповідати на цьому сервері без обов’язкового @mentioned" + + > "Дозволь моєму агенту відповідати на цьому сервері без потреби в @mention" - - Установіть `requireMention: false` у конфігурації сервера: + + Задайте `requireMention: false` у конфігурації гільдії: ```json5 { @@ -248,47 +248,47 @@ openclaw pairing approve discord - - Типово довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях приватних повідомлень. У каналах сервера `MEMORY.md` автоматично не завантажується. + + Типово довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях приватних повідомлень. У каналах гільдії `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. -- Типово (`session.dmScope=main`) приватні чати використовують основну сесію агента (`agent:main:main`). -- Канали серверів мають ізольовані ключі сесій (`agent::discord:channel:`). -- Групові приватні чати типово ігноруються (`channels.discord.dm.groupEnabled=false`). -- Власні слеш-команди виконуються в ізольованих сесіях команд (`agent::discord:slash:`), при цьому все одно несуть `CommandTargetSessionKey` до маршрутизованої сесії розмови. +- Gateway володіє з’єднанням Discord. +- Маршрутизація відповідей детермінована: вхідні повідомлення Discord отримують відповіді назад у Discord. +- Типово (`session.dmScope=main`) прямі чати спільно використовують основну сесію агента (`agent:main:main`). +- Канали гільдії мають ізольовані ключі сесій (`agent::discord:channel:`). +- Групові приватні повідомлення типово ігноруються (`channels.discord.dm.groupEnabled=false`). +- Нативні слеш-команди виконуються в ізольованих сесіях команд (`agent::discord:slash:`), водночас зберігаючи `CommandTargetSessionKey` для маршрутизації до сесії розмови. ## Канали форуму -Канали форуму й медіаканали Discord приймають лише публікації в тредах. OpenClaw підтримує два способи їх створення: +Канали форуму та медіаканали Discord приймають лише дописи в тредах. OpenClaw підтримує два способи їх створення: - Надішліть повідомлення до батьківського форуму (`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: \ @@ -299,31 +299,31 @@ openclaw message thread create --channel discord --target channel: \ ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із навантаженням `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте message tool із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: - `text`, `section`, `separator`, `actions`, `media-gallery`, `file` -- Рядки дій дозволяють до 5 кнопок або одне меню вибору +- Рядки дій допускають до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -Типово компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, виборів і форм, доки не сплине термін їх дії. +Типово компоненти одноразові. Задайте `components.reusable=true`, щоб дозволити багаторазове використання кнопок, виборів і форм, доки не спливе їхній термін дії. -Щоб обмежити, хто може натискати кнопку, задайте `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо налаштовано, користувачі, які не збігаються з умовами, отримують ефемерну відмову. +Щоб обмежити, хто може натискати кнопку, задайте `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо це налаштовано, користувачі, які не відповідають умовам, отримають ephemeral-відмову. -Слеш-команди `/model` і `/models` відкривають інтерактивний засіб вибору моделі з випадними списками провайдера й моделі та кроком Submit. Відповідь засобу вибору є ефемерною, і лише користувач, який її викликав, може нею користуватися. +Слеш-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадними списками провайдера і моделі та кроком Submit. Відповідь вибору є ephemeral, і використовувати її може лише користувач, який викликав команду. Вкладення файлів: -- блоки `file` мають вказувати на посилання вкладення (`attachment://`) -- Надайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів -- Використовуйте `filename`, щоб перевизначити ім’я завантаження, коли воно має збігатися з посиланням вкладення +- Блоки `file` мають вказувати на посилання вкладення (`attachment://`) +- Надайте вкладення через `media`/`path`/`filePath` (один файл); для кількох файлів використовуйте `media-gallery` +- Використовуйте `filename`, щоб перевизначити ім’я завантаження, коли воно має відповідати посиланню вкладення Модальні форми: -- Додайте `components.modal` із максимум 5 полями +- Додайте `components.modal` з максимум 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- OpenClaw автоматично додає кнопку-тригер +- OpenClaw автоматично додає кнопку запуску Приклад: @@ -341,7 +341,7 @@ OpenClaw підтримує контейнери компонентів Discord type: "actions", buttons: [ { - label: "Схвалити", + label: "Підтвердити", style: "success", allowedUsers: ["123456789012345678"], }, @@ -352,10 +352,10 @@ OpenClaw підтримує контейнери компонентів Discord type: "actions", select: { type: "string", - placeholder: "Виберіть варіант", + placeholder: "Виберіть опцію", options: [ - { label: "Варіант A", value: "a" }, - { label: "Варіант B", value: "b" }, + { label: "Опція A", value: "a" }, + { label: "Опція B", value: "b" }, ], }, }, @@ -382,15 +382,15 @@ OpenClaw підтримує контейнери компонентів Discord ## Керування доступом і маршрутизація - - `channels.discord.dmPolicy` керує доступом до приватних повідомлень (застаріле: `channels.discord.dm.policy`): + + `channels.discord.dmPolicy` керує доступом до DM (застаріле: `channels.discord.dm.policy`): - `pairing` (типово) - `allowlist` - `open` (потребує, щоб `channels.discord.allowFrom` містив `"*"`; застаріле: `channels.discord.dm.allowFrom`) - `disabled` - Якщо політика приватних повідомлень не є open, невідомі користувачі блокуються (або отримують запит на підключення в режимі `pairing`). + Якщо політика DM не є open, невідомі користувачі блокуються (або отримують запит на зіставлення в режимі `pairing`). Пріоритет для кількох облікових записів: @@ -398,32 +398,32 @@ OpenClaw підтримує контейнери компонентів Discord - Іменовані облікові записи успадковують `channels.discord.allowFrom`, якщо їхній власний `allowFrom` не задано. - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. - Формат цілі приватних повідомлень для доставки: + Формат цілі DM для доставки: - `user:` - згадка `<@id>` - Прості числові ID є неоднозначними й відхиляються, якщо явно не вказано тип цілі user/channel. + Числові ID без префікса є неоднозначними й відхиляються, якщо явно не вказано тип цілі user/channel. - - Обробка серверів керується `channels.discord.groupPolicy`: + + Обробка гільдій керується через `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Безпечним базовим значенням, коли існує `channels.discord`, є `allowlist`. + Безпечний базовий варіант, коли існує `channels.discord`, — `allowlist`. Поведінка `allowlist`: - - сервер має збігатися з `channels.discord.guilds` (перевага надається `id`, slug також приймається) - - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволяються, коли вони збігаються з `users` АБО `roles` - - пряме зіставлення імен/тегів типово вимкнене; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності - - для `users` підтримуються імена/теги, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів - - якщо для сервера налаштовано `channels`, канали, яких немає в списку, відхиляються - - якщо сервер не має блоку `channels`, дозволяються всі канали в цьому allowlist-сервері + - гільдія має відповідати `channels.discord.guilds` (`id` бажано, slug також приймається) + - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволяються, коли вони відповідають `users` АБО `roles` + - пряме зіставлення імен/тегів типово вимкнене; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності + - для `users` підтримуються імена/теги, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи з іменами/тегами + - якщо для гільдії налаштовано `channels`, канали, яких немає у списку, відхиляються + - якщо в гільдії немає блоку `channels`, дозволяються всі канали в цій allowlist-гілдії Приклад: @@ -449,23 +449,23 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Якщо ви лише задаєте `DISCORD_BOT_TOKEN` і не створюєте блок `channels.discord`, резервним значенням середовища виконання буде `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. + Якщо ви лише задали `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, резервний варіант runtime буде `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. - - Повідомлення серверів типово вимагають згадки. + + Повідомлення гільдії типово вимагають згадки. Виявлення згадок включає: - явну згадку бота - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) - - неявну поведінку reply-to-bot у підтримуваних випадках + - неявну поведінку відповіді боту в підтримуваних випадках - `requireMention` налаштовується для кожного сервера/каналу (`channels.discord.guilds...`). + `requireMention` налаштовується для кожної гільдії/каналу окремо (`channels.discord.guilds...`). `ignoreOtherMentions` за потреби відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). - Групові приватні повідомлення: + Групові DM: - типово: ігноруються (`dm.groupEnabled=false`) - необов’язковий allowlist через `dm.groupChannels` (ID каналів або slug) @@ -473,9 +473,9 @@ OpenClaw підтримує контейнери компонентів Discord -### Маршрутизація агента на основі ролей +### Маршрутизація агентів за ролями -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників серверів Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише для серверів. Якщо прив’язка також задає інші поля збігу (наприклад, `peer` + `guildId` + `roles`), мають збігатися всі налаштовані поля. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише для гільдії. Якщо прив’язка також задає інші поля match (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -502,7 +502,7 @@ OpenClaw підтримує контейнери компонентів Discord ## Налаштування Developer Portal - + 1. Discord Developer Portal -> **Applications** -> **New Application** 2. **Bot** -> **Add Bot** @@ -510,13 +510,13 @@ OpenClaw підтримує контейнери компонентів Discord - + У **Bot -> Privileged Gateway Intents** увімкніть: - Message Content Intent - Server Members Intent (рекомендовано) - Presence intent є необов’язковим і потрібен лише якщо ви хочете отримувати оновлення присутності. Налаштування присутності бота (`setPresence`) не потребує ввімкнення оновлень присутності для учасників. + Інтент присутності необов’язковий і потрібен лише якщо ви хочете отримувати оновлення присутності. Установлення присутності бота (`setPresence`) не потребує ввімкнення оновлень присутності для учасників. @@ -534,73 +534,74 @@ OpenClaw підтримує контейнери компонентів Discord - Attach Files - Add Reactions (необов’язково) - Уникайте `Administrator`, якщо в цьому немає явної потреби. + Уникайте `Administrator`, якщо це не потрібно явно. - - Увімкніть у Discord режим розробника, а потім скопіюйте: + + Увімкніть режим розробника Discord, а потім скопіюйте: - ID сервера - ID каналу - ID користувача - Для надійних аудитів і перевірок віддавайте перевагу числовим ID у конфігурації OpenClaw. + Віддавайте перевагу числовим ID у config OpenClaw для надійних аудитів і перевірок. -## Власні команди та авторизація команд +## Нативні команди та авторизація команд - `commands.native` типово має значення `"auto"` і ввімкнене для Discord. -- Перевизначення для конкретного каналу: `channels.discord.commands.native`. -- `commands.native=false` явно очищає раніше зареєстровані власні команди Discord. -- Авторизація власних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимими в інтерфейсі Discord для користувачів, які не мають авторизації; виконання все одно дотримується авторизації OpenClaw і повертає «не авторизовано». +- Перевизначення для окремого каналу: `channels.discord.commands.native`. +- `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. +- Авторизація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимими в UI Discord для користувачів без авторизації; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". -Див. [Слеш-команди](/uk/tools/slash-commands), щоб ознайомитися з каталогом команд і поведінкою. +Див. [Slash commands](/uk/tools/slash-commands) щодо каталогу команд і поведінки. -Типові параметри слеш-команд: +Типові налаштування слеш-команд: - `ephemeral: true` -## Подробиці функцій +## Деталі функцій - - Discord підтримує теги reply у виводі агента: + + Discord підтримує теги відповідей у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` - Керуються через `channels.discord.replyToMode`: + Керується через `channels.discord.replyToMode`: - `off` (типово) - `first` - `all` - `batched` - Примітка: `off` вимикає неявне threading відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - `first` завжди додає неявне власне посилання reply до першого вихідного повідомлення Discord у межах ходу. - `batched` додає неявне власне посилання reply Discord лише тоді, коли + Примітка: `off` вимикає неявне зв’язування відповідей у треди. Явні теги `[[reply_to_*]]` усе одно враховуються. + `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord у цьому ході. + `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли вхідний хід був debounce-пакетом із кількох повідомлень. Це корисно, - коли вам потрібні власні reply переважно для неоднозначних діалогів із - раптовими серіями повідомлень, а не для кожного окремого ходу з одним повідомленням. + коли ви хочете нативні відповіді переважно для неоднозначних чатів зі сплесками, а не для кожного + окремого ходу з одним повідомленням. - ID повідомлень виводяться в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень виводяться в context/history, щоб агенти могли націлюватися на конкретні повідомлення. - - OpenClaw може передавати чернетки відповідей у потоковому режимі, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. + + OpenClaw може потоково передавати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. - - `channels.discord.streaming` керує потоковим попереднім переглядом (`off` | `partial` | `block` | `progress`, типово: `off`). - - Типовим значенням залишається `off`, оскільки редагування попереднього перегляду в Discord може швидко впиратися в ліміти частоти, особливо коли кілька ботів або шлюзів спільно використовують один обліковий запис чи трафік сервера. - - `progress` приймається для узгодженості між каналами й у Discord зіставляється з `partial`. - - `channels.discord.streamMode` є застарілим псевдонімом і мігрує автоматично. + - `channels.discord.streaming` керує потоковою передачею попереднього перегляду (`off` | `partial` | `block` | `progress`, типово: `off`). + - Типовим лишається `off`, оскільки редагування попереднього перегляду в Discord може швидко впертися в обмеження швидкості, особливо коли кілька ботів або шлюзів використовують той самий обліковий запис чи трафік гільдії. + - `progress` приймається для узгодженості між каналами та зіставляється з `partial` у Discord. + - `channels.discord.streamMode` — застарілий псевдонім, який автоматично мігрується. - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` надсилає фрагменти розміру чернетки (використовуйте `draftChunk` для налаштування розміру та точок розриву). - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме повідомлення попереднього перегляду чернетки (типово: `true`). Установіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу. + - `block` виводить фрагменти розміру чернетки (використовуйте `draftChunk` для налаштування розміру і точок розриву). + - Фінальні відповіді з медіа, помилками та явними відповідями скасовують відкладені редагування попереднього перегляду без виведення тимчасової чернетки перед звичайною доставкою. + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме повідомлення чернетки попереднього перегляду (типово: `true`). Установіть `false`, щоб зберігати окремі повідомлення інструментів/прогресу. Приклад: @@ -614,7 +615,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Типові значення фрагментації режиму `block` (обмежуються значенням `channels.discord.textChunkLimit`): + Типові значення фрагментації для режиму `block` (обмежуються до `channels.discord.textChunkLimit`): ```json5 { @@ -633,19 +634,19 @@ OpenClaw підтримує контейнери компонентів Discord Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. - Примітка: потоковий попередній перегляд відокремлений від потокової передачі блоків. Коли потокова передача блоків явно - ввімкнена для Discord, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі. + Примітка: потоковий попередній перегляд відокремлений від потокової передачі блоками. Коли для Discord явно + ввімкнено потокову передачу блоками, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі. - Контекст історії серверів: + Контекст історії гільдії: - `channels.discord.historyLimit` типово `20` - резервне значення: `messages.groupChat.historyLimit` - `0` вимикає - Керування історією приватних повідомлень: + Керування історією DM: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` @@ -654,26 +655,26 @@ OpenClaw підтримує контейнери компонентів Discord - треди Discord маршрутизуються як сесії каналів - метадані батьківського треду можуть використовуватися для зв’язування з батьківською сесією - - конфігурація треду успадковує конфігурацію батьківського каналу, якщо немає окремого запису для треду + - конфігурація треду успадковує конфігурацію батьківського каналу, якщо не існує окремого запису для треду - Теми каналів додаються як **ненадійний** контекст (а не як system prompt). - Контекст reply і цитованих повідомлень наразі залишається таким, як був отриманий. - Allowlist у Discord насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + Теми каналів інжектуються як **ненадійний** контекст (не як системний prompt). + Контекст відповідей і процитованих повідомлень наразі залишається в тому вигляді, в якому його отримано. + Allowlist Discord насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - - Discord може прив’язати тред до цілі сесії, щоб наступні повідомлення в цьому треді й надалі маршрутизувалися до тієї самої сесії (включно із сесіями субагентів). + + Discord може прив’язати тред до цілі сесії, щоб подальші повідомлення в цьому треді й надалі маршрутизувалися до тієї самої сесії (включно із сесіями субагентів). Команди: - - `/focus ` прив’язує поточний/новий тред до цілі субагента/сесії - - `/unfocus` видаляє поточну прив’язку треду - - `/agents` показує активні запуски та стан прив’язки - - `/session idle ` переглядає/оновлює автоматичне зняття фокуса через неактивність для прив’язок у фокусі - - `/session max-age ` переглядає/оновлює жорсткий максимальний вік для прив’язок у фокусі + - `/focus ` прив’язати поточний/новий тред до цілі субагента/сесії + - `/unfocus` прибрати поточну прив’язку треду + - `/agents` показати активні запуски і стан прив’язки + - `/session idle ` переглянути/оновити автоматичне зняття фокуса через неактивність для фокусованих прив’язок + - `/session max-age ` переглянути/оновити жорсткий максимальний вік для фокусованих прив’язок - Конфігурація: + Config: ```json5 { @@ -690,7 +691,7 @@ OpenClaw підтримує контейнери компонентів Discord enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // увімкнення за потреби + spawnSubagentSessions: false, // вмикається явно }, }, }, @@ -705,14 +706,14 @@ OpenClaw підтримує контейнери компонентів Discord - `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). + Див. [Sub-agents](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Configuration Reference](/uk/gateway/configuration-reference). - - Для стабільних «постійно активних» робочих просторів ACP налаштуйте типізовані прив’язки ACP верхнього рівня, націлені на розмови в Discord. + + Для стабільних «always-on» робочих просторів ACP налаштуйте типізовані прив’язки ACP верхнього рівня, націлені на розмови Discord. - Шлях конфігурації: + Шлях config: - `bindings[]` з `type: "acp"` і `match.channel: "discord"` @@ -766,51 +767,51 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або тред Discord на місці та зберігає маршрутизацію майбутніх повідомлень до тієї самої ACP-сесії. - - Це все ще може означати «запустити нову ACP-сесію Codex», але саме по собі не створює новий тред Discord. Наявний канал залишається поверхнею чату. - - Codex усе ще може працювати у власному `cwd` або робочому просторі бекенда на диску. Цей робочий простір є станом середовища виконання, а не тредом Discord. - - Повідомлення треду можуть успадковувати ACP-прив’язку батьківського каналу. - - У прив’язаному каналі або треді `/new` і `/reset` скидають ту саму ACP-сесію на місці. - - Тимчасові прив’язки тредів усе ще працюють і можуть перевизначати визначення цілі, поки вони активні. - - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірній тред через `--thread auto|here`. Він не потрібен для `/acp spawn ... --bind here` у поточному каналі. + - `/acp spawn codex --bind here` прив’язує поточний канал або тред Discord на місці й надалі спрямовує майбутні повідомлення до тієї самої сесії ACP. + - Це все ще може означати «запустити нову сесію Codex ACP», але саме по собі не створює новий тред Discord. Наявний канал залишається поверхнею чату. + - Codex усе одно може працювати у власному `cwd` або робочому просторі backend на диску. Цей робочий простір є станом runtime, а не тредом Discord. + - Повідомлення треду можуть успадковувати прив’язку ACP батьківського каналу. + - У прив’язаному каналі або треді `/new` і `/reset` скидають ту саму сесію ACP на місці. + - Тимчасові прив’язки тредів усе ще працюють і можуть перевизначати визначення цілі, поки активні. + - `spawnAcpSessions` потрібне лише тоді, коли OpenClaw має створити/прив’язати дочірній тред через `--thread auto|here`. Воно не потрібне для `/acp spawn ... --bind here` у поточному каналі. - Див. [ACP Agents](/uk/tools/acp-agents), щоб дізнатися подробиці про поведінку прив’язок. + Див. [ACP Agents](/uk/tools/acp-agents) щодо деталей поведінки прив’язок. - Режим сповіщень про реакції для кожного сервера: + Режим сповіщень про реакції для кожної гільдії: - `off` - `own` (типово) - `all` - `allowlist` (використовує `guilds..users`) - Події реакцій перетворюються на системні події та прикріплюються до маршрутизованої Discord-сесії. + Події реакцій перетворюються на системні події та приєднуються до маршрутизованої сесії Discord. - `ackReaction` надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення. + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - резервне значення емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Discord приймає Unicode-емодзі або назви користувацьких емодзі. - - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Discord приймає emoji Unicode або назви користувацьких emoji. + - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. - - Записи конфігурації, ініційовані з каналу, типово ввімкнені. + + Записи config, ініційовані з каналу, типово ввімкнені. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). + Це впливає на потоки `/config set|unset` (коли ввімкнені можливості команд). Вимкнення: @@ -827,7 +828,7 @@ OpenClaw підтримує контейнери компонентів Discord - Маршрутизуйте трафік WebSocket шлюзу Discord і стартові REST-запити (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + Маршрутизуйте трафік WebSocket шлюзу Discord і REST-запити під час запуску (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. ```json5 { @@ -839,7 +840,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Перевизначення для облікового запису: + Перевизначення для окремого облікового запису: ```json5 { @@ -866,7 +867,7 @@ OpenClaw підтримує контейнери компонентів Discord discord: { pluralkit: { enabled: true, - token: "pk_live_...", // необов’язково; потрібно для приватних систем + token: "pk_live_...", // необов’язково; потрібен для приватних систем }, }, }, @@ -877,15 +878,15 @@ OpenClaw підтримує контейнери компонентів Discord - allowlist можуть використовувати `pk:` - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошуки використовують ID початкового повідомлення й обмежуються часовим вікном - - якщо пошук не вдався, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо не задано `allowBots=true` + - пошук використовує ID вихідного повідомлення й обмежується часовим вікном + - якщо пошук не вдається, проксійовані повідомлення обробляються як повідомлення бота та відкидаються, якщо не задано `allowBots=true` - Оновлення присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичну присутність. + Оновлення присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте auto presence. - Приклад лише зі статусом: + Приклад лише статусу: ```json5 { @@ -897,13 +898,13 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Приклад активності (користувацький статус є типовим типом активності): + Приклад активності (custom status — типовий тип активності): ```json5 { channels: { discord: { - activity: "Час фокусування", + activity: "Час фокусу", activityType: 4, }, }, @@ -916,7 +917,7 @@ OpenClaw підтримує контейнери компонентів Discord { channels: { discord: { - activity: "Кодування наживо", + activity: "Live coding", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, @@ -924,16 +925,16 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Мапа типів активності: + Відповідність типів активності: - 0: Playing - 1: Streaming (потрібен `activityUrl`) - 2: Listening - 3: Watching - - 4: Custom (використовує текст активності як стан статусу; емодзі необов’язкове) + - 4: Custom (використовує текст активності як стан статусу; emoji необов’язковий) - 5: Competing - Приклад автоматичної присутності (сигнал працездатності середовища виконання): + Приклад auto presence (сигнал стану runtime): ```json5 { @@ -950,7 +951,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Автоматична присутність зіставляє доступність середовища виконання зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: + Auto presence зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -958,49 +959,49 @@ OpenClaw підтримує контейнери компонентів Discord - - Discord підтримує обробку підтверджень на основі кнопок у приватних повідомленнях і за потреби може публікувати запити на підтвердження в каналі походження. + + Discord підтримує обробку погоджень через кнопки в DM і за потреби може публікувати запити на погодження в початковому каналі. - Шлях конфігурації: + Шлях config: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовується резервне значення з `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 автоматично вмикає нативні exec approvals, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного погоджувача — або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не визначає exec approvers із `allowFrom` каналу, застарілого `dm.allowFrom` або `defaultTo` прямих повідомлень. Задайте `enabled: false`, щоб явно вимкнути Discord як нативний клієнт погоджень. - Коли `target` має значення `channel` або `both`, запит на підтвердження видимий у каналі. Лише визначені затверджувачі можуть використовувати кнопки; інші користувачі отримують ефемерну відмову. Запити на підтвердження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw повертається до доставки через приватні повідомлення. + Коли `target` має значення `channel` або `both`, запит на погодження видно в каналі. Лише визначені погоджувачі можуть використовувати кнопки; інші користувачі отримують ephemeral-відмову. Запити на погодження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw переходить до доставки через DM. - Discord також відтворює спільні кнопки підтвердження, які використовуються іншими чат-каналами. Власний адаптер Discord головно додає маршрутизацію підтверджень затверджувачам у приватні повідомлення та fanout у канали. - Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw - має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, - що чат-підтвердження недоступні або єдиним шляхом є ручне підтвердження. + Discord також відтворює спільні кнопки погодження, які використовуються іншими чат-каналами. Нативний адаптер Discord головним чином додає маршрутизацію DM погоджувачів і fanout у канали. + Коли ці кнопки присутні, вони є основним UX для погоджень; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат tool повідомляє, + що погодження через чат недоступні або ручне погодження — єдиний шлях. Авторизація Gateway для цього обробника використовує той самий спільний контракт визначення облікових даних, що й інші клієнти Gateway: - - локальна авторизація env-first (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`, потім `gateway.auth.*`) - - у локальному режимі `gateway.remote.*` можуть використовуватися як резервне значення лише коли `gateway.auth.*` не задано; налаштовані, але не визначені локальні SecretRef завершуються в закритому режимі - - підтримка віддаленого режиму через `gateway.remote.*`, коли застосовно - - перевизначення URL безпечні щодо перевизначень: перевизначення CLI не повторно використовують неявні облікові дані, а перевизначення env використовують лише облікові дані env + - локальна auth із пріоритетом env (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`, потім `gateway.auth.*`) + - у локальному режимі `gateway.remote.*` можна використовувати як резервний варіант лише коли `gateway.auth.*` не задано; налаштовані, але невизначені локальні SecretRef блокуються + - підтримка віддаленого режиму через `gateway.remote.*`, коли це застосовно + - перевизначення URL безпечні для перевизначення: перевизначення CLI не використовують неявні облікові дані повторно, а перевизначення env використовують лише облікові дані env - Поведінка визначення підтверджень: + Поведінка визначення погоджень: - ID з префіксом `plugin:` визначаються через `plugin.approval.resolve`. - Інші ID визначаються через `exec.approval.resolve`. - - Discord тут не виконує додатковий резервний перехід exec-to-plugin; префікс - id визначає, який метод gateway буде викликано. + - Discord не робить тут додаткового резервного переходу exec-to-plugin; префікс + ID визначає, який метод gateway буде викликано. - Термін дії exec-підтверджень типово спливає через 30 хвилин. Якщо підтвердження завершуються помилкою з - невідомими ID підтвердження, перевірте визначення затверджувачів, увімкнення функції та - чи збігається тип доставленого id підтвердження з очікуваним запитом. + Термін дії exec approvals типово спливає через 30 хвилин. Якщо погодження завершуються помилкою з + невідомими ID погоджень, перевірте визначення погоджувачів, увімкнення функції й + те, що доставлений тип ID погодження відповідає очікуваному запиту. Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals) -## Інструменти та шлюзи дій +## Інструменти та обмеження дій Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. @@ -1011,11 +1012,11 @@ OpenClaw підтримує контейнери компонентів Discord - модерація: `timeout`, `kick`, `ban` - присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або локальний шлях до файла), щоб задати обкладинку запланованої події. +Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файлу), щоб задати обкладинку запланованої події. -Шлюзи дій знаходяться в `channels.discord.actions.*`. +Обмеження дій розташовані в `channels.discord.actions.*`. -Типова поведінка шлюзів: +Типова поведінка обмежень: | Група дій | Типово | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | @@ -1024,13 +1025,13 @@ OpenClaw підтримує контейнери компонентів Discord | moderation | disabled | | presence | disabled | -## Інтерфейс Components v2 +## UI компонентів v2 -OpenClaw використовує Discord components v2 для exec-підтверджень і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для користувацького інтерфейсу (розширено; потребує створення навантаження компонента через інструмент discord), тоді як застарілі `embeds` усе ще доступні, але не рекомендовані. +OpenClaw використовує компоненти Discord v2 для exec approvals і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для власного UI (розширено; потребує побудови payload компонента через Discord tool), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. -- `channels.discord.ui.components.accentColor` задає акцентний колір, що використовується контейнерами компонентів Discord (hex). -- Задайте для кожного облікового запису через `channels.discord.accounts..ui.components.accentColor`. -- `embeds` ігноруються, коли присутні components v2. +- `channels.discord.ui.components.accentColor` задає акцентний колір, який використовується контейнерами компонентів Discord (hex). +- Задайте для окремого облікового запису через `channels.discord.accounts..ui.components.accentColor`. +- `embeds` ігноруються, коли присутні компоненти v2. Приклад: @@ -1050,15 +1051,15 @@ OpenClaw використовує Discord components v2 для exec-підтве ## Голосові канали -OpenClaw може приєднуватися до голосових каналів Discord для безперервних розмов у реальному часі. Це окремо від вкладень голосових повідомлень. +OpenClaw може приєднуватися до голосових каналів Discord для розмов у реальному часі безперервного типу. Це окрема функція від вкладень голосових повідомлень. Вимоги: -- Увімкніть власні команди (`commands.native` або `channels.discord.commands.native`). +- Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). - Налаштуйте `channels.discord.voice`. -- Бот повинен мати дозволи Connect + Speak у цільовому голосовому каналі. +- Бот потребує дозволів Connect + Speak у цільовому голосовому каналі. -Використовуйте власну команду лише для Discord `/vc join|leave|status` для керування сесіями. Команда використовує типового агента облікового запису й дотримується тих самих правил allowlist і group policy, що й інші команди Discord. +Використовуйте нативну команду лише для Discord `/vc join|leave|status`, щоб керувати сесіями. Команда використовує типового агента облікового запису й дотримується тих самих правил allowlist і group policy, що й інші команди Discord. Приклад автоматичного приєднання: @@ -1089,22 +1090,22 @@ OpenClaw може приєднуватися до голосових канал Примітки: - `voice.tts` перевизначає `messages.tts` лише для відтворення голосу. -- Ходи розшифрування голосу визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). -- Голос типово ввімкнений; установіть `channels.discord.voice.enabled=false`, щоб вимкнути його. +- Ходи голосової транскрипції визначають статус власника з `allowFrom` Discord (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). +- Голос типово ввімкнений; задайте `channels.discord.voice.enabled=false`, щоб його вимкнути. - `voice.daveEncryption` і `voice.decryptionFailureTolerance` напряму передаються в параметри приєднання `@discordjs/voice`. -- Типові значення `@discordjs/voice`: `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. -- OpenClaw також відстежує збої розшифрування під час приймання й автоматично відновлюється, виходячи та повторно приєднуючись до голосового каналу після повторних збоїв за короткий проміжок часу. -- Якщо журнали приймання постійно показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути помилка приймання `@discordjs/voice` на боці upstream, відстежувана в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). +- Якщо не задано, типові значення `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`. +- OpenClaw також відстежує помилки дешифрування під час отримання і автоматично відновлюється, виходячи з голосового каналу й повторно приєднуючись після повторних збоїв у короткому часовому вікні. +- Якщо журнали отримання неодноразово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути помилка отримання в upstream `@discordjs/voice`, відстежувана в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). ## Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд хвильової форми й потребують аудіо OGG/Opus разом із метаданими. OpenClaw генерує хвильову форму автоматично, але для цього на хості Gateway мають бути доступні `ffmpeg` і `ffprobe`, щоб аналізувати та конвертувати аудіофайли. +Голосові повідомлення Discord показують попередній перегляд хвильової форми й потребують аудіо OGG/Opus плюс метадані. OpenClaw генерує хвильову форму автоматично, але для перевірки й конвертації аудіофайлів на хості gateway мають бути доступні `ffmpeg` і `ffprobe`. Вимоги й обмеження: -- Надайте **локальний шлях до файла** (URL відхиляються). +- Надайте **шлях до локального файлу** (URL відхиляються). - Не додавайте текстовий вміст (Discord не дозволяє текст + голосове повідомлення в одному payload). -- Приймається будь-який аудіоформат; OpenClaw за потреби конвертує його в OGG/Opus. +- Приймається будь-який аудіоформат; за потреби OpenClaw конвертує його в OGG/Opus. Приклад: @@ -1115,19 +1116,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Усунення проблем - + - увімкніть Message Content Intent - - увімкніть Server Members Intent, якщо ви покладаєтеся на визначення користувачів/учасників - - перезапустіть gateway після зміни інтендів + - увімкніть Server Members Intent, якщо ви залежите від визначення користувача/учасника + - перезапустіть gateway після зміни інтентів - + - перевірте `groupPolicy` - - перевірте allowlist серверів у `channels.discord.guilds` - - якщо існує мапа `channels` сервера, дозволені лише канали зі списку + - перевірте allowlist гільдії в `channels.discord.guilds` + - якщо існує мапа `channels` гільдії, дозволено лише канали зі списку - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1143,13 +1144,13 @@ openclaw logs --follow Поширені причини: - - `groupPolicy="allowlist"` без відповідного allowlist сервера/каналу - - `requireMention` налаштовано не в тому місці (має бути під `channels.discord.guilds` або в записі каналу) - - відправника заблоковано allowlist `users` сервера/каналу + - `groupPolicy="allowlist"` без відповідної allowlist гільдії/каналу + - `requireMention` налаштовано не в тому місці (має бути в `channels.discord.guilds` або в записі каналу) + - відправника блокує allowlist `users` гільдії/каналу - + Типові журнали: @@ -1162,13 +1163,13 @@ openclaw logs --follow - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` - Параметр тайм-ауту виконання worker: + Параметр тайм-ауту worker run: - один обліковий запис: `channels.discord.inboundWorker.runTimeoutMs` - кілька облікових записів: `channels.discord.accounts..inboundWorker.runTimeoutMs` - - типове значення: `1800000` (30 хвилин); установіть `0`, щоб вимкнути + - типово: `1800000` (30 хвилин); задайте `0`, щоб вимкнути - Рекомендоване базове значення: + Рекомендований базовий варіант: ```json5 { @@ -1189,40 +1190,40 @@ openclaw logs --follow } ``` - Використовуйте `eventQueue.listenerTimeout` для повільного налаштування listener і `inboundWorker.runTimeoutMs` - лише якщо вам потрібен окремий запобіжник для чергових ходів агента. + Використовуйте `eventQueue.listenerTimeout` для повільного налаштування listener, а `inboundWorker.runTimeoutMs` + лише якщо вам потрібен окремий запобіжник для поставлених у чергу ходів агента. Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. - Якщо ви використовуєте ключі slug, зіставлення під час виконання все ще може працювати, але probe не може повністю перевірити дозволи. + Якщо ви використовуєте ключі slug, зіставлення в runtime все одно може працювати, але probe не може повністю перевірити дозволи. - + - - приватні повідомлення вимкнено: `channels.discord.dm.enabled=false` - - політику приватних повідомлень вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) - - очікується підтвердження підключення в режимі `pairing` + - DM вимкнено: `channels.discord.dm.enabled=false` + - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) + - очікується підтвердження зіставлення в режимі `pairing` Типово повідомлення, створені ботом, ігноруються. - Якщо ви встановлюєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. + Якщо ви задали `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. Віддавайте перевагу `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` - якщо збої тривають після автоматичного повторного приєднання, зберіть журнали й порівняйте з [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) @@ -1230,19 +1231,19 @@ openclaw logs --follow -## Вказівники на довідник із конфігурації +## Вказівники на reference конфігурації -Основний довідник: +Основний reference: -- [Довідник із конфігурації - Discord](/uk/gateway/configuration-reference#discord) +- [Configuration reference - Discord](/uk/gateway/configuration-reference#discord) Важливі поля Discord: -- запуск/авторизація: `enabled`, `token`, `accounts.*`, `allowBots` +- запуск/auth: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` -- команда: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` +- команди: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - черга подій: `eventQueue.listenerTimeout` (бюджет listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- вхідний worker: `inboundWorker.runTimeoutMs` +- inbound worker: `inboundWorker.runTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` - потокова передача: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` @@ -1250,21 +1251,21 @@ openclaw logs --follow - `mediaMaxMb` обмежує вихідні завантаження Discord (типово: `100MB`) - дії: `actions.*` - присутність: `activity`, `status`, `activityType`, `activityUrl` -- інтерфейс: `ui.components.accentColor` +- UI: `ui.components.accentColor` - функції: `threadBindings`, верхньорівневий `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` -## Безпека й експлуатація +## Безпека й операції -- Розглядайте токени ботів як секрети (у контрольованих середовищах перевага за `DISCORD_BOT_TOKEN`). -- Надавайте Discord дозволи за принципом найменших привілеїв. -- Якщо розгортання/стан команди застаріли, перезапустіть gateway і повторно перевірте через `openclaw channels status --probe`. +- Розглядайте токени бота як секрети (у керованих середовищах бажано `DISCORD_BOT_TOKEN`). +- Надавайте Discord лише мінімально необхідні дозволи. +- Якщо розгортання/стан команд застаріли, перезапустіть gateway і повторно перевірте через `openclaw channels status --probe`. ## Пов’язане -- [Підключення](/uk/channels/pairing) +- [Зіставлення](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Маршрутизація каналів](/uk/channels/channel-routing) - [Безпека](/uk/gateway/security) - [Маршрутизація кількох агентів](/uk/concepts/multi-agent) - [Усунення проблем](/uk/channels/troubleshooting) -- [Слеш-команди](/uk/tools/slash-commands) +- [Slash commands](/uk/tools/slash-commands) diff --git a/docs/uk/channels/mattermost.md b/docs/uk/channels/mattermost.md index 1d9829de8..56d60ac5a 100644 --- a/docs/uk/channels/mattermost.md +++ b/docs/uk/channels/mattermost.md @@ -5,10 +5,10 @@ read_when: summary: Налаштування бота Mattermost і конфігурація OpenClaw title: Mattermost x-i18n: - generated_at: "2026-04-21T20:11:23Z" + generated_at: "2026-04-22T01:34:45Z" model: gpt-5.4 provider: openai - source_hash: 76a182ad26199f435de64edc27c888672964b711a7346f3ca539fba666695222 + source_hash: dd3059c5e64f417edc02c3e850ddd066e38decda0cbdcea31e1c57136e6bcb1d source_path: channels/mattermost.md workflow: 15 --- @@ -16,13 +16,13 @@ x-i18n: # Mattermost Статус: вбудований Plugin (токен бота + події WebSocket). Підтримуються канали, групи та приватні повідомлення. -Mattermost — це платформа командного обміну повідомленнями, яку можна самостійно розгорнути; деталі про продукт і завантаження дивіться на офіційному сайті +Mattermost — це команда платформа обміну повідомленнями, яку можна самостійно розгорнути; докладніше про продукт і завантаження дивіться на офіційному сайті [mattermost.com](https://mattermost.com). ## Вбудований Plugin -Mattermost постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайним -пакетованим збіркам не потрібне окреме встановлення. +Mattermost постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайним +пакетним збіркам не потрібне окреме встановлення. Якщо ви використовуєте старішу збірку або спеціальне встановлення без Mattermost, встановіть його вручну: @@ -39,12 +39,12 @@ openclaw plugins install @openclaw/mattermost openclaw plugins install ./path/to/local/mattermost-plugin ``` -Деталі: [Plugins](/uk/tools/plugin) +Докладніше: [Plugins](/uk/tools/plugin) ## Швидке налаштування 1. Переконайтеся, що Plugin Mattermost доступний. - - У поточних пакетованих випусках OpenClaw він уже вбудований. + - У поточних пакетних релізах OpenClaw він уже вбудований. - У старіших/спеціальних встановленнях його можна додати вручну командами вище. 2. Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**. 3. Скопіюйте **базову URL-адресу** Mattermost (наприклад, `https://chat.example.com`). @@ -65,10 +65,10 @@ openclaw plugins install ./path/to/local/mattermost-plugin } ``` -## Вбудовані slash-команди +## Власні slash-команди -Вбудовані slash-команди є опційними. Якщо їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через -Mattermost API і отримує callback POST-запити на HTTP-сервері Gateway. +Власні slash-команди є необов’язковими. Коли їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через +API Mattermost і отримує callback POST-запити на HTTP-сервері Gateway. ```json5 { @@ -89,36 +89,36 @@ Mattermost API і отримує callback POST-запити на HTTP-серве Примітки: - `native: "auto"` типово вимкнено для Mattermost. Установіть `native: true`, щоб увімкнути. -- Якщо `callbackUrl` пропущено, OpenClaw виводить його з хоста/порту Gateway + `callbackPath`. -- Для конфігурацій із кількома обліковими записами `commands` можна задати на верхньому рівні або в +- Якщо `callbackUrl` не вказано, OpenClaw формує його на основі host/port Gateway + `callbackPath`. +- Для багатoоблікових конфігурацій `commands` можна задати на верхньому рівні або в `channels.mattermost.accounts..commands` (значення облікового запису мають пріоритет над полями верхнього рівня). -- Callback-и команд перевіряються за токенами окремих команд, які повертає - Mattermost, коли OpenClaw реєструє команди `oc_*`. -- Callback-и slash-команд відхиляються за принципом fail closed, якщо реєстрація не вдалася, запуск був частковим або - токен callback-а не збігається з жодною із зареєстрованих команд. -- Вимога доступності: endpoint callback-а має бути доступний із сервера Mattermost. - - Не встановлюйте `callbackUrl` на `localhost`, якщо Mattermost не працює на тому самому хості/в тому самому мережевому просторі імен, що й OpenClaw. - - Не встановлюйте `callbackUrl` на базову URL-адресу Mattermost, якщо ця URL-адреса не reverse-proxy-ює `/api/channels/mattermost/command` до OpenClaw. - - Швидка перевірка: `curl https:///api/channels/mattermost/command`; GET-запит має повертати `405 Method Not Allowed` від OpenClaw, а не `404`. -- Вимога allowlist вихідних з’єднань Mattermost: - - Якщо ваш callback націлено на приватні/tailnet/внутрішні адреси, установіть у Mattermost - `ServiceSettings.AllowedUntrustedInternalConnections`, щоб він містив хост/домен callback-а. - - Використовуйте записи хоста/домену, а не повні URL-адреси. - - Добре: `gateway.tailnet-name.ts.net` - - Погано: `https://gateway.tailnet-name.ts.net` +- Command callback-и перевіряються за допомогою токенів для кожної команди, які + Mattermost повертає, коли OpenClaw реєструє команди `oc_*`. +- Callback-и slash-команд закриваються з відмовою, якщо реєстрація не вдалася, запуск був частковим або + callback token не збігається з одним із зареєстрованих команд. +- Вимога доступності: endpoint callback-ів має бути доступним із сервера Mattermost. + - Не вказуйте `callbackUrl` як `localhost`, якщо Mattermost не працює на тому ж host/namespace мережі, що й OpenClaw. + - Не вказуйте `callbackUrl` як базову URL-адресу Mattermost, якщо ця URL-адреса не reverse-proxy-ює `/api/channels/mattermost/command` до OpenClaw. + - Швидка перевірка: `curl https:///api/channels/mattermost/command`; GET має повертати `405 Method Not Allowed` від OpenClaw, а не `404`. +- Вимога allowlist вихідних підключень Mattermost: + - Якщо ваш callback спрямовано на private/tailnet/internal-адреси, налаштуйте в Mattermost + `ServiceSettings.AllowedUntrustedInternalConnections`, щоб включити host/domain callback-а. + - Використовуйте записи host/domain, а не повні URL-адреси. + - Правильно: `gateway.tailnet-name.ts.net` + - Неправильно: `https://gateway.tailnet-name.ts.net` ## Змінні середовища (обліковий запис за замовчуванням) -Установіть їх на хості Gateway, якщо надаєте перевагу змінним середовища: +Установіть їх на host Gateway, якщо віддаєте перевагу змінним середовища: - `MATTERMOST_BOT_TOKEN=...` - `MATTERMOST_URL=https://chat.example.com` -Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів треба використовувати значення конфігурації. +Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів потрібно використовувати значення з конфігурації. ## Режими чату -Mattermost автоматично відповідає на приватні повідомлення. Поведінка в каналах керується через `chatmode`: +Mattermost автоматично відповідає на приватні повідомлення. Поведінка в каналах керується параметром `chatmode`: - `oncall` (типово): відповідати в каналах лише за @згадки. - `onmessage`: відповідати на кожне повідомлення в каналі. @@ -140,18 +140,18 @@ Mattermost автоматично відповідає на приватні п Примітки: - `onchar` усе одно відповідає на явні @згадки. -- `channels.mattermost.requireMention` підтримується для застарілих конфігурацій, але рекомендовано `chatmode`. +- `channels.mattermost.requireMention` враховується для застарілих конфігурацій, але рекомендовано `chatmode`. -## Потоки й сесії +## Гілки та сесії Використовуйте `channels.mattermost.replyToMode`, щоб керувати тим, чи відповіді в каналах і групах залишаються в -основному каналі, чи запускають потік під дописом, який їх спричинив. +основному каналі, чи запускають гілку під повідомленням, яке їх спричинило. -- `off` (типово): відповідати в потоці лише тоді, коли вхідний допис уже в потоці. -- `first`: для дописів верхнього рівня в каналі/групі запускати потік під цим дописом і спрямовувати - розмову в сесію, прив’язану до потоку. +- `off` (типово): відповідати в гілці лише тоді, коли вхідне повідомлення вже в ній. +- `first`: для повідомлень верхнього рівня в каналі/групі запускати гілку під цим повідомленням і спрямовувати + розмову до сесії, прив’язаної до гілки. - `all`: наразі для Mattermost поводиться так само, як `first`. -- Приватні повідомлення ігнорують цей параметр і залишаються без потоків. +- Для прямих повідомлень цей параметр ігнорується, і вони залишаються поза гілками. Приклад конфігурації: @@ -167,9 +167,9 @@ Mattermost автоматично відповідає на приватні п Примітки: -- Сесії з областю дії потоку використовують id допису, який його ініціював, як корінь потоку. -- `first` і `all` наразі еквівалентні, тому що щойно Mattermost має корінь потоку, - наступні частини й медіа продовжують надсилатися в той самий потік. +- Сесії, прив’язані до гілки, використовують id повідомлення-тригера як корінь гілки. +- `first` і `all` зараз еквівалентні, тому що щойно в Mattermost з’являється корінь гілки, + подальші фрагменти та медіа продовжуються в тій самій гілці. ## Керування доступом (приватні повідомлення) @@ -183,9 +183,9 @@ Mattermost автоматично відповідає на приватні п - Типово: `channels.mattermost.groupPolicy = "allowlist"` (із вимогою згадки). - Додавайте відправників до allowlist через `channels.mattermost.groupAllowFrom` (рекомендовано ID користувачів). -- Перевизначення згадок для окремих каналів знаходяться в `channels.mattermost.groups..requireMention` - або в `channels.mattermost.groups["*"].requireMention` як значення за замовчуванням. -- Зіставлення `@username` є змінним і ввімкнене лише коли `channels.mattermost.dangerouslyAllowNameMatching: true`. +- Перевизначення згадок для окремих каналів розміщуються в `channels.mattermost.groups..requireMention` + або в `channels.mattermost.groups["*"].requireMention` як типове значення. +- Відповідність `@username` є змінною та вмикається лише за `channels.mattermost.dangerouslyAllowNameMatching: true`. - Відкриті канали: `channels.mattermost.groupPolicy="open"` (із вимогою згадки). - Примітка щодо runtime: якщо `channels.mattermost` повністю відсутній, runtime повертається до `groupPolicy="allowlist"` для перевірок груп (навіть якщо встановлено `channels.defaults.groupPolicy`). @@ -207,25 +207,25 @@ Mattermost автоматично відповідає на приватні п ## Цілі для вихідної доставки -Використовуйте ці формати цілей із `openclaw message send` або Cron/Webhook: +Використовуйте ці формати цілей із `openclaw message send` або cron/webhooks: - `channel:` для каналу - `user:` для приватного повідомлення -- `@username` для приватного повідомлення (визначається через Mattermost API) +- `@username` для приватного повідомлення (визначається через API Mattermost) -Прості непрозорі ID (наприклад, `64ifufp...`) у Mattermost **неоднозначні** (ID користувача чи ID каналу). +Прості непрозорі ID (як-от `64ifufp...`) у Mattermost **неоднозначні** (ID користувача чи ID каналу). OpenClaw визначає їх у порядку **спочатку користувач**: - Якщо ID існує як користувач (`GET /api/v4/users/` виконується успішно), OpenClaw надсилає **приватне повідомлення**, визначаючи прямий канал через `/api/v4/channels/direct`. -- Інакше ID вважається **ID каналу**. +- Інакше ID трактується як **ID каналу**. Якщо вам потрібна детермінована поведінка, завжди використовуйте явні префікси (`user:` / `channel:`). -## Повторні спроби для каналу приватних повідомлень +## Повторні спроби для DM-каналу -Коли OpenClaw надсилає повідомлення до цілі приватних повідомлень Mattermost і спочатку має визначити прямий канал, -типово він повторює спроби в разі тимчасових збоїв створення прямого каналу. +Коли OpenClaw надсилає повідомлення до цілі Mattermost DM і спочатку має визначити прямий канал, +типово він повторює спроби у разі тимчасових збоїв створення прямого каналу. Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для Plugin Mattermost, або `channels.mattermost.accounts..dmChannelRetry` для окремого облікового запису. @@ -247,15 +247,15 @@ OpenClaw визначає їх у порядку **спочатку корист Примітки: -- Це застосовується лише до створення каналу приватних повідомлень (`/api/v4/channels/direct`), а не до кожного виклику Mattermost API. -- Повторні спроби застосовуються до тимчасових збоїв, таких як обмеження швидкості, відповіді 5xx і мережеві помилки або помилки тайм-ауту. -- Помилки клієнта 4xx, окрім `429`, вважаються постійними й не повторюються. +- Це стосується лише створення DM-каналу (`/api/v4/channels/direct`), а не кожного виклику API Mattermost. +- Повторні спроби застосовуються до тимчасових збоїв, як-от обмеження частоти, відповіді 5xx та помилки мережі або тайм-аути. +- Клієнтські помилки 4xx, окрім `429`, вважаються постійними й не повторюються. -## Попередній перегляд streaming +## Потокове попереднє відображення -Mattermost передає thinking, активність інструментів і частковий текст відповіді в один **чорновий допис попереднього перегляду**, який фіналізується на місці, коли остаточну відповідь безпечно надсилати. Попередній перегляд оновлюється в тому самому id допису, а не засмічує канал повідомленнями для кожного фрагмента. +Mattermost передає thinking, активність інструментів і частковий текст відповіді в одному **чернетковому повідомленні попереднього перегляду**, яке фіналізується на місці, коли остаточну відповідь безпечно надсилати. Попередній перегляд оновлюється в межах того самого id повідомлення, замість того щоб засмічувати канал повідомленнями на кожен фрагмент. Остаточні повідомлення з медіа/помилками скасовують відкладені редагування попереднього перегляду й використовують звичайну доставку замість публікації одноразового повідомлення попереднього перегляду. -Увімкнення через `channels.mattermost.streaming`: +Увімкніть через `channels.mattermost.streaming`: ```json5 { @@ -269,20 +269,20 @@ Mattermost передає thinking, активність інструменті Примітки: -- `partial` — звичайний вибір: один допис попереднього перегляду, який редагується в міру зростання відповіді, а потім фіналізується повною відповіддю. -- `block` використовує чорнові фрагменти у стилі додавання всередині допису попереднього перегляду. -- `progress` показує попередній перегляд статусу під час генерації і публікує остаточну відповідь лише після завершення. -- `off` вимикає preview streaming. -- Якщо потік неможливо фіналізувати на місці (наприклад, якщо допис було видалено посеред потоку), OpenClaw повертається до надсилання нового остаточного допису, щоб відповідь ніколи не була втрачена. -- Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці зіставлення каналів. +- `partial` — звичний вибір: одне повідомлення попереднього перегляду, яке редагується в міру зростання відповіді, а потім фіналізується повною відповіддю. +- `block` використовує чернеткові фрагменти у стилі додавання в межах повідомлення попереднього перегляду. +- `progress` показує статусне попереднє повідомлення під час генерації й публікує остаточну відповідь лише після завершення. +- `off` вимикає потокове попереднє відображення. +- Якщо потік неможливо фіналізувати на місці (наприклад, якщо повідомлення було видалено посеред потоку), OpenClaw повертається до надсилання нового остаточного повідомлення, щоб відповідь ніколи не була втрачена. +- Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці відповідності каналів. -## Реакції (інструмент повідомлень) +## Реакції (інструмент message) - Використовуйте `message action=react` з `channel=mattermost`. -- `messageId` — це id допису Mattermost. +- `messageId` — це id повідомлення Mattermost. - `emoji` приймає назви на кшталт `thumbsup` або `:+1:` (двокрапки необов’язкові). - Установіть `remove=true` (boolean), щоб видалити реакцію. -- Події додавання/видалення реакцій пересилаються як системні події до сесії агента, до якої виконується маршрутизація. +- Події додавання/видалення реакцій пересилаються як системні події до сесії агента за маршрутом. Приклади: @@ -293,12 +293,12 @@ message action=react channel=mattermost target=channel: messageId=.actions.reactions`. +- `channels.mattermost.actions.reactions`: увімкнення/вимкнення дій із реакціями (типово true). +- Перевизначення для окремого облікового запису: `channels.mattermost.accounts..actions.reactions`. -## Інтерактивні кнопки (інструмент повідомлень) +## Інтерактивні кнопки (інструмент message) -Надсилайте повідомлення з кнопками, які можна натискати. Коли користувач натискає кнопку, агент отримує +Надсилайте повідомлення з кнопками, на які можна натискати. Коли користувач натискає кнопку, агент отримує вибір і може відповісти. Увімкніть кнопки, додавши `inlineButtons` до можливостей каналу: @@ -313,29 +313,29 @@ message action=react channel=mattermost target=channel: messageId= buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]] ``` -Поля кнопок: +Поля кнопки: - `text` (обов’язково): мітка для відображення. -- `callback_data` (обов’язково): значення, яке повертається після натискання (використовується як ID дії). +- `callback_data` (обов’язково): значення, яке надсилається назад при натисканні (використовується як ID дії). - `style` (необов’язково): `"default"`, `"primary"` або `"danger"`. Коли користувач натискає кнопку: 1. Усі кнопки замінюються рядком підтвердження (наприклад, "✓ **Yes** selected by @user"). -2. Агент отримує вибір як вхідне повідомлення і відповідає. +2. Агент отримує вибір як вхідне повідомлення й відповідає. Примітки: -- Callback-и кнопок використовують перевірку HMAC-SHA256 (автоматично, без додаткової конфігурації). -- Mattermost видаляє callback data зі своїх API-відповідей (функція безпеки), тому після натискання - видаляються всі кнопки — часткове видалення неможливе. -- ID дій, які містять дефіси або підкреслення, автоматично санітизуються +- Callback-и кнопок використовують перевірку HMAC-SHA256 (автоматично, конфігурація не потрібна). +- Mattermost прибирає callback data зі своїх відповідей API (функція безпеки), тому всі кнопки + видаляються після натискання — часткове видалення неможливе. +- ID дій, що містять дефіси або підкреслення, автоматично санітизуються (обмеження маршрутизації Mattermost). Конфігурація: @@ -345,20 +345,20 @@ message action=send channel=mattermost target=channel: buttons=[[{"te - `channels.mattermost.interactions.callbackBaseUrl`: необов’язкова зовнішня базова URL-адреса для callback-ів кнопок (наприклад, `https://gateway.example.com`). Використовуйте це, коли Mattermost не може напряму дістатися до Gateway за його bind host. -- У конфігураціях із кількома обліковими записами це саме поле також можна встановити в +- У багатoоблікових конфігураціях те саме поле також можна вказати в `channels.mattermost.accounts..interactions.callbackBaseUrl`. -- Якщо `interactions.callbackBaseUrl` пропущено, OpenClaw виводить URL-адресу callback-а з +- Якщо `interactions.callbackBaseUrl` не вказано, OpenClaw формує callback URL на основі `gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:`. -- Правило доступності: URL-адреса callback-а кнопок має бути доступна із сервера Mattermost. - `localhost` працює лише тоді, коли Mattermost і OpenClaw працюють на тому самому хості/в тому самому мережевому просторі імен. -- Якщо ціль вашого callback-а є приватною/tailnet/внутрішньою, додайте її хост/домен до Mattermost +- Правило доступності: URL callback-ів кнопок має бути доступним із сервера Mattermost. + `localhost` працює лише тоді, коли Mattermost і OpenClaw працюють на одному host/namespace мережі. +- Якщо ваша ціль callback-а є private/tailnet/internal, додайте її host/domain до Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`. ### Пряма інтеграція з API (зовнішні скрипти) -Зовнішні скрипти та Webhook можуть публікувати кнопки безпосередньо через Mattermost REST API +Зовнішні скрипти та Webhook-и можуть публікувати кнопки безпосередньо через REST API Mattermost замість використання інструмента `message` агента. За можливості використовуйте `buildButtonAttachments()` з -extension; якщо публікуєте сирий JSON, дотримуйтеся цих правил: +розширення; якщо публікуєте сирий JSON, дотримуйтеся таких правил: **Структура payload:** @@ -372,7 +372,7 @@ extension; якщо публікуєте сирий JSON, дотримуйтес actions: [ { id: "mybutton01", // лише буквено-цифрові символи — див. нижче - type: "button", // обов’язково, інакше натискання тихо ігноруються + type: "button", // обов’язково, інакше натискання буде мовчки проігноровано name: "Approve", // мітка для відображення style: "primary", // необов’язково: "default", "primary", "danger" integration: { @@ -380,7 +380,7 @@ extension; якщо публікуєте сирий JSON, дотримуйтес context: { action_id: "mybutton01", // має збігатися з id кнопки (для пошуку назви) action: "approve", - // ... будь-які власні поля ... + // ... будь-які користувацькі поля ... _token: "", // див. розділ HMAC нижче }, }, @@ -392,29 +392,29 @@ extension; якщо публікуєте сирий JSON, дотримуйтес } ``` -**Критичні правила:** +**Критично важливі правила:** -1. Attachments розміщуються в `props.attachments`, а не у верхньорівневому `attachments` (інакше тихо ігноруються). -2. Для кожної дії потрібне `type: "button"` — без нього натискання тихо поглинаються. -3. Для кожної дії потрібне поле `id` — Mattermost ігнорує дії без ID. -4. `id` дії має бути **лише буквено-цифровим** (`[a-zA-Z0-9]`). Дефіси й підкреслення ламають - серверну маршрутизацію дій Mattermost (повертає 404). Видаляйте їх перед використанням. +1. Attachments мають бути в `props.attachments`, а не у верхньорівневому `attachments` (інакше їх буде мовчки проігноровано). +2. Кожна дія потребує `type: "button"` — без цього натискання будуть мовчки проковтнуті. +3. Кожна дія потребує поля `id` — Mattermost ігнорує дії без ID. +4. `id` дії має бути **лише буквено-цифровим** (`[a-zA-Z0-9]`). Дефіси та підкреслення ламають + серверну маршрутизацію дій у Mattermost (повертається 404). Видаляйте їх перед використанням. 5. `context.action_id` має збігатися з `id` кнопки, щоб у повідомленні підтвердження показувалася назва кнопки (наприклад, "Approve"), а не сирий ID. -6. `context.action_id` є обов’язковим — без нього обробник взаємодії повертає 400. +6. `context.action_id` є обов’язковим — без нього обробник взаємодій повертає 400. **Генерація HMAC-токена:** Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти мають генерувати токени, -які збігаються з логікою перевірки Gateway: +які відповідають логіці перевірки Gateway: -1. Виведіть secret із токена бота: +1. Виведіть секрет із токена бота: `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` 2. Побудуйте об’єкт context з усіма полями **крім** `_token`. -3. Серіалізуйте з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify` +3. Серіалізуйте його з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify` з відсортованими ключами, що дає компактний вивід). 4. Підпишіть: `HMAC-SHA256(key=secret, data=serializedContext)` -5. Додайте отриманий hex digest як `_token` у context. +5. Додайте отриманий hex-digest як `_token` у context. Приклад на Python: @@ -433,24 +433,24 @@ token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() context = {**ctx, "_token": token} ``` -Поширені помилки з HMAC: +Поширені пастки HMAC: - `json.dumps` у Python типово додає пробіли (`{"key": "val"}`). Використовуйте `separators=(",", ":")`, щоб відповідати компактному виводу JavaScript (`{"key":"val"}`). -- Завжди підписуйте **всі** поля context (без `_token`). Gateway видаляє `_token`, а потім - підписує все, що залишилося. Підписування лише підмножини спричиняє тиху помилку перевірки. +- Завжди підписуйте **всі** поля context (без `_token`). Gateway прибирає `_token`, а потім + підписує все, що залишилося. Підписування підмножини спричиняє мовчазний збій перевірки. - Використовуйте `sort_keys=True` — Gateway сортує ключі перед підписуванням, а Mattermost може змінювати порядок полів context під час збереження payload. -- Виводьте secret із токена бота (детерміновано), а не з випадкових байтів. Secret +- Виводьте секрет із токена бота (детерміновано), а не з випадкових байтів. Секрет має бути однаковим у процесі, що створює кнопки, і в Gateway, який їх перевіряє. ## Адаптер каталогу Plugin Mattermost містить адаптер каталогу, який визначає назви каналів і користувачів -через Mattermost API. Це дає змогу використовувати цілі `#channel-name` і `@username` у -`openclaw message send` та доставках Cron/Webhook. +через API Mattermost. Це дає змогу використовувати цілі `#channel-name` і `@username` у +`openclaw message send` та доставках cron/Webhook. -Жодна конфігурація не потрібна — адаптер використовує токен бота з конфігурації облікового запису. +Конфігурація не потрібна — адаптер використовує токен бота з конфігурації облікового запису. ## Кілька облікових записів @@ -474,31 +474,31 @@ Mattermost підтримує кілька облікових записів у - Немає відповідей у каналах: переконайтеся, що бот є в каналі, і згадайте його (oncall), використайте префікс-тригер (onchar) або встановіть `chatmode: "onmessage"`. - Помилки автентифікації: перевірте токен бота, базову URL-адресу та чи ввімкнено обліковий запис. - Проблеми з кількома обліковими записами: змінні середовища застосовуються лише до облікового запису `default`. -- Вбудовані slash-команди повертають `Unauthorized: invalid command token.`: OpenClaw - не прийняв токен callback-а. Типові причини: - - реєстрація slash-команд не вдалася або завершилася лише частково під час запуску +- Власні slash-команди повертають `Unauthorized: invalid command token.`: OpenClaw + не прийняв callback token. Типові причини: + - реєстрація slash-команд не вдалася або була завершена лише частково під час запуску - callback надходить до неправильного Gateway/облікового запису - - Mattermost усе ще має старі команди, що вказують на попередню ціль callback-а - - Gateway було перезапущено без повторної активації slash-команд -- Якщо вбудовані slash-команди перестали працювати, перевірте журнали на + - Mattermost досі має старі команди, що вказують на попередню ціль callback-а + - Gateway перезапустився без повторної активації slash-команд +- Якщо власні slash-команди перестали працювати, перевірте логи на наявність `mattermost: failed to register slash commands` або `mattermost: native slash commands enabled but no commands could be registered`. -- Якщо `callbackUrl` пропущено й журнали попереджають, що callback було визначено як - `http://127.0.0.1:18789/...`, ця URL-адреса, імовірно, доступна лише коли - Mattermost працює на тому самому хості/в тому самому мережевому просторі імен, що й OpenClaw. Натомість установіть - явну зовні доступну `commands.callbackUrl`. +- Якщо `callbackUrl` не вказано і в логах є попередження, що callback визначився як + `http://127.0.0.1:18789/...`, ця URL-адреса, ймовірно, доступна лише тоді, + коли Mattermost працює на тому самому host/namespace мережі, що й OpenClaw. Установіть + явний зовнішньо доступний `commands.callbackUrl`. - Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Переконайтеся, що кожна кнопка має поля `text` і `callback_data`. -- Кнопки відображаються, але натискання нічого не роблять: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost містить `127.0.0.1 localhost`, а `EnablePostActionIntegration` у ServiceSettings має значення `true`. -- Після натискання кнопок повертається 404: `id` кнопки, імовірно, містить дефіси або підкреслення. Маршрутизатор дій Mattermost ламається на небуквено-цифрових ID. Використовуйте лише `[a-zA-Z0-9]`. -- У журналах Gateway є `invalid _token`: невідповідність HMAC. Переконайтеся, що ви підписуєте всі поля context (а не підмножину), використовуєте відсортовані ключі та компактний JSON (без пробілів). Див. розділ HMAC вище. -- У журналах Gateway є `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що воно включене під час побудови payload інтеграції. -- Підтвердження показує сирий ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Установіть однакове санітизоване значення для обох. +- Кнопки відображаються, але натискання нічого не робить: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost містить `127.0.0.1 localhost`, а `EnablePostActionIntegration` у ServiceSettings має значення `true`. +- Кнопки повертають 404 при натисканні: `id` кнопки, імовірно, містить дефіси або підкреслення. Маршрутизатор дій Mattermost ламається на небуквено-цифрових ID. Використовуйте лише `[a-zA-Z0-9]`. +- У логах Gateway є `invalid _token`: невідповідність HMAC. Переконайтеся, що ви підписуєте всі поля context (а не підмножину), використовуєте відсортовані ключі та компактний JSON (без пробілів). Див. розділ HMAC вище. +- У логах Gateway є `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що його включено під час побудови payload інтеграції. +- У підтвердженні показується сирий ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Установіть для обох однакове санітизоване значення. - Агент не знає про кнопки: додайте `capabilities: ["inlineButtons"]` до конфігурації каналу Mattermost. -## Пов’язані матеріали +## Пов’язане - [Channels Overview](/uk/channels) — усі підтримувані канали - [Pairing](/uk/channels/pairing) — автентифікація приватних повідомлень і потік pairing - [Groups](/uk/channels/groups) — поведінка групового чату та вимога згадки - [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Security](/uk/gateway/security) — модель доступу та посилення безпеки +- [Security](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/channels/slack.md b/docs/uk/channels/slack.md index c39cbaedd..63fda151e 100644 --- a/docs/uk/channels/slack.md +++ b/docs/uk/channels/slack.md @@ -1,29 +1,29 @@ --- read_when: - Налаштування Slack або налагодження режиму сокета/HTTP у Slack -summary: Налаштування Slack та поведінка під час виконання (Socket Mode + URL-адреси HTTP-запитів) +summary: Налаштування Slack і поведінка під час виконання (Socket Mode + URL-адреси HTTP-запитів) title: Slack x-i18n: - generated_at: "2026-04-21T16:52:58Z" + generated_at: "2026-04-22T01:34:39Z" model: gpt-5.4 provider: openai - source_hash: f30b372a3ae10b7b649532181306e42792aca76b41422516e9633eb79f73f009 + source_hash: e80b1ff7dfe3124916f9a4334badc9a742a0d0843b37c77838ede9f830920ff7 source_path: channels/slack.md workflow: 15 --- # Slack -Статус: готовий до продакшн-використання для приватних повідомлень і каналів через інтеграції застосунку Slack. Режим за замовчуванням — Socket Mode; URL-адреси HTTP-запитів також підтримуються. +Статус: готовий до продакшену для DM + каналів через інтеграції застосунку Slack. Типовий режим — Socket Mode; URL-адреси HTTP-запитів також підтримуються. - - Для приватних повідомлень Slack за замовчуванням використовується режим зв’язування. + + Для Slack DM типовим є режим прив’язування. - + Нативна поведінка команд і каталог команд. - + Міжканальна діагностика та сценарії відновлення. @@ -31,13 +31,13 @@ x-i18n: ## Швидке налаштування - + У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: - виберіть **from a manifest** і виберіть робочий простір для вашого застосунку - - вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче та продовжте створення + - вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче й продовжуйте створення - згенеруйте **App-Level Token** (`xapp-...`) з `connections:write` - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) @@ -57,7 +57,7 @@ x-i18n: } ``` - Резервний варіант через змінні середовища (лише для облікового запису за замовчуванням): + Резервний варіант через змінні середовища (лише типовий обліковий запис): ```bash SLACK_APP_TOKEN=xapp-... @@ -106,9 +106,9 @@ openclaw gateway ``` - Використовуйте унікальні шляхи Webhook для багатьох облікових записів HTTP + Використовуйте унікальні шляхи webhook для багатьох HTTP-облікових записів - Надайте кожному обліковому запису окремий `webhookPath` (за замовчуванням `/slack/events`), щоб реєстрації не конфліктували. + Надайте кожному обліковому запису окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували. @@ -128,7 +128,7 @@ openclaw gateway ## Контрольний список маніфесту та областей доступу - + ```json { @@ -289,22 +289,22 @@ openclaw gateway -### Додаткові налаштування маніфесту +### Додаткові параметри маніфесту -Відобразіть різні можливості, які розширюють наведені вище значення за замовчуванням. +Відображають різні можливості, які розширюють наведені вище типові налаштування. - + - Кілька [нативних slash-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами: + Кілька [нативних слеш-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами: - Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована. - - Одночасно можна зробити доступними не більше 25 slash-команд. + - Одночасно можна зробити доступними не більше 25 слеш-команд. Замініть ваш наявний розділ `features.slash_commands` на підмножину [доступних команд](/uk/tools/slash-commands#command-list): - + ```json "slash_commands": [ @@ -437,7 +437,7 @@ openclaw gateway }, { "command": "/compact", - "description": "Ущільнити контекст сесії", + "description": "Виконати Compaction контексту сесії", "usage_hint": "[instructions]", "url": "https://gateway-host.example.com/slack/events" }, @@ -454,7 +454,7 @@ openclaw gateway }, { "command": "/think", - "description": "Встановити рівень обмірковування", + "description": "Установити рівень мислення", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, @@ -478,13 +478,13 @@ openclaw gateway }, { "command": "/elevated", - "description": "Перемкнути розширений режим", + "description": "Перемкнути підвищений режим", "usage_hint": "[on|off|ask|full]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/exec", - "description": "Показати або встановити параметри exec за замовчуванням", + "description": "Показати або встановити типові параметри exec", "usage_hint": "host= security= ask= node=", "url": "https://gateway-host.example.com/slack/events" }, @@ -502,7 +502,7 @@ openclaw gateway }, { "command": "/help", - "description": "Показати короткий підсумок довідки", + "description": "Показати коротке зведення довідки", "url": "https://gateway-host.example.com/slack/events" }, { @@ -518,7 +518,7 @@ openclaw gateway }, { "command": "/agentstatus", - "description": "Показати статус під час виконання, включно з використанням провайдера/квотою, якщо доступно", + "description": "Показати статус виконання, зокрема використання/квоту провайдера, коли доступно", "url": "https://gateway-host.example.com/slack/events" }, { @@ -539,19 +539,19 @@ openclaw gateway }, { "command": "/skill", - "description": "Запустити skill за назвою", + "description": "Запустити Skills за назвою", "usage_hint": " [input]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/btw", - "description": "Поставити додаткове запитання без зміни контексту сесії", + "description": "Поставити побічне запитання без зміни контексту сесії", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/usage", - "description": "Керувати нижнім колонтитулом використання або показати підсумок вартості", + "description": "Керувати нижнім колонтитулом використання або показати зведення вартості", "usage_hint": "off|tokens|full|cost", "url": "https://gateway-host.example.com/slack/events" } @@ -563,9 +563,9 @@ openclaw gateway - Додайте область доступу бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували активну ідентичність агента (власне ім’я користувача та значок) замість стандартної ідентичності застосунку Slack. + Додайте область доступу бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власне ім’я користувача та піктограму) замість типової ідентичності застосунку Slack. - Якщо ви використовуєте значок emoji, Slack очікує синтаксис `:emoji_name:`. + Якщо ви використовуєте піктограму emoji, Slack очікує синтаксис `:emoji_name:`. @@ -584,103 +584,103 @@ openclaw gateway ## Модель токенів -- Для Socket Mode обов’язкові `botToken` + `appToken`. +- `botToken` + `appToken` обов’язкові для Socket Mode. - Для режиму HTTP потрібні `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають прості текстові +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні рядки або об’єкти SecretRef. - Токени в конфігурації мають пріоритет над резервним варіантом через env. -- Резервний варіант через змінні середовища `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до облікового запису за замовчуванням. -- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного варіанту через env) і за замовчуванням працює в режимі лише читання (`userTokenReadOnly: true`). +- Резервний варіант через env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до типового облікового запису. +- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного варіанта через env) і типово працює лише для читання (`userTokenReadOnly: true`). Поведінка знімка стану: - Перевірка облікового запису Slack відстежує поля `*Source` і `*Status` для кожного облікового запису (`botToken`, `appToken`, `signingSecret`, `userToken`). - Статус може бути `available`, `configured_unavailable` або `missing`. -- `configured_unavailable` означає, що обліковий запис налаштований через SecretRef - або інше не вбудоване джерело секретів, але поточна команда/шлях виконання - не змогли визначити фактичне значення. +- `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef + або інше не-inline джерело секрету, але поточний шлях команди/виконання + не зміг визначити фактичне значення. - У режимі HTTP включається `signingSecretStatus`; у Socket Mode обов’язковою парою є `botTokenStatus` + `appTokenStatus`. -Для дій/читання каталогу можна надавати перевагу токену користувача, якщо його налаштовано. Для запису перевага зберігається за токеном бота; запис через токен користувача дозволений лише тоді, коли `userTokenReadOnly: false` і токен бота недоступний. +Для дій/читання директорій за наявності конфігурації перевага може надаватися токену користувача. Для запису пріоритетним залишається токен бота; запис через токен користувача дозволено лише коли `userTokenReadOnly: false`, а токен бота недоступний. ## Дії та обмеження -Дії Slack контролюються через `channels.slack.actions.*`. +Дії Slack керуються через `channels.slack.actions.*`. -Доступні групи дій у поточному наборі інструментів Slack: +Доступні групи дій у поточному інструментарії Slack: | Group | Default | | ---------- | ------- | -| повідомлення | увімкнено | -| реакції | увімкнено | -| закріплення | увімкнено | -| інформація про учасника | увімкнено | -| список emoji | увімкнено | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | Поточні дії з повідомленнями Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. -## Контроль доступу та маршрутизація +## Керування доступом і маршрутизація - - `channels.slack.dmPolicy` керує доступом до приватних повідомлень (застаріле: `channels.slack.dm.policy`): + + `channels.slack.dmPolicy` керує доступом до DM (застаріле: `channels.slack.dm.policy`): - - `pairing` (за замовчуванням) + - `pairing` (типово) - `allowlist` - - `open` (вимагає, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`) + - `open` (потребує, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`) - `disabled` - Прапорці приватних повідомлень: + Прапорці DM: - - `dm.enabled` (за замовчуванням true) - - `channels.slack.allowFrom` (рекомендовано) + - `dm.enabled` (типово true) + - `channels.slack.allowFrom` (бажано) - `dm.allowFrom` (застаріле) - - `dm.groupEnabled` (групові приватні повідомлення за замовчуванням false) + - `dm.groupEnabled` (групові DM типово false) - `dm.groupChannels` (необов’язковий allowlist MPIM) - Пріоритет у багатьох облікових записах: + Пріоритет для кількох облікових записів: - `channels.slack.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - Іменовані облікові записи успадковують `channels.slack.allowFrom`, якщо їхній власний `allowFrom` не встановлено. - Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`. - Зв’язування в приватних повідомленнях використовує `openclaw pairing approve slack `. + Прив’язування в DM використовує `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` керує обробкою каналів: - `open` - `allowlist` - `disabled` - Allowlist каналів розміщується в `channels.slack.channels` і має використовувати стабільні ID каналів. + Allowlist каналів міститься в `channels.slack.channels` і має використовувати стабільні ідентифікатори каналів. - Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується `groupPolicy="allowlist"` і записується попередження в журнал (навіть якщо встановлено `channels.defaults.groupPolicy`). + Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується резервне значення `groupPolicy="allowlist"` і журналюється попередження (навіть якщо встановлено `channels.defaults.groupPolicy`). - Розпізнавання імен/ID: + Визначення імен/ідентифікаторів: - - записи allowlist для каналів і приватних повідомлень розпізнаються під час запуску, коли доступ токена це дозволяє - - нерозпізнані записи назв каналів зберігаються як налаштовані, але за замовчуванням ігноруються для маршрутизації - - вхідна авторизація та маршрутизація каналів за замовчуванням орієнтовані на ID; пряме зіставлення з іменем користувача/slug вимагає `channels.slack.dangerouslyAllowNameMatching: true` + - записи allowlist каналів і записи allowlist DM визначаються під час запуску, якщо доступ токена це дозволяє + - нерозпізнані записи назв каналів зберігаються як налаштовані, але типово ігноруються для маршрутизації + - вхідна авторизація та маршрутизація каналів типово орієнтовані на ID; пряме зіставлення з іменем користувача/slug потребує `channels.slack.dangerouslyAllowNameMatching: true` - Повідомлення в каналах за замовчуванням обмежуються згадками. + Повідомлення в каналах типово обмежуються згадками. Джерела згадок: - явна згадка застосунку (`<@botId>`) - - шаблони регулярних виразів для згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`) - - неявна поведінка відповіді в потоці бота (вимикається, коли `thread.requireExplicitMention` дорівнює `true`) + - шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`) + - неявна поведінка відповіді в потоці до бота (вимикається, коли `thread.requireExplicitMention` має значення `true`) - Елементи керування для кожного каналу (`channels.slack.channels.`; імена лише через розпізнавання під час запуску або `dangerouslyAllowNameMatching`): + Керування для кожного каналу (`channels.slack.channels.`; імена — лише через визначення під час запуску або `dangerouslyAllowNameMatching`): - `requireMention` - `users` (allowlist) @@ -688,38 +688,38 @@ openclaw gateway - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - формат ключа `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або шаблон `"*"` + - формат ключів `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або символ підстановки `"*"` (застарілі ключі без префікса, як і раніше, зіставляються лише з `id:`) -## Потоки, сесії та теги відповідей +## Потоки, сесії та теги відповіді -- Приватні повідомлення маршрутизуються як `direct`; канали — як `channel`; MPIM — як `group`. -- Із типовим `session.dmScope=main` приватні повідомлення Slack згортаються до основної сесії агента. +- DM маршрутизуються як `direct`; канали — як `channel`; MPIM — як `group`. +- Із типовим `session.dmScope=main` Slack DM згортаються в основну сесію агента. - Сесії каналів: `agent::slack:channel:`. - Відповіді в потоках можуть створювати суфікси сесій потоку (`:thread:`) коли це застосовно. -- Значення за замовчуванням для `channels.slack.thread.historyScope` — `thread`; для `thread.inheritParent` — `false`. -- `channels.slack.thread.initialHistoryLimit` визначає, скільки наявних повідомлень потоку вибирається під час запуску нової сесії потоку (за замовчуванням `20`; встановіть `0`, щоб вимкнути). -- `channels.slack.thread.requireExplicitMention` (за замовчуванням `false`): якщо `true`, пригнічує неявні згадки в потоці, щоб бот відповідав лише на явні згадки `@bot` усередині потоків, навіть коли бот уже брав участь у потоці. Без цього відповіді в потоці, де брав участь бот, обходять обмеження `requireMention`. +- Типове значення `channels.slack.thread.historyScope` — `thread`; типове значення `thread.inheritParent` — `false`. +- `channels.slack.thread.initialHistoryLimit` керує тим, скільки наявних повідомлень потоку буде отримано під час запуску нової сесії потоку (типово `20`; установіть `0`, щоб вимкнути). +- `channels.slack.thread.requireExplicitMention` (типово `false`): коли значення `true`, пригнічує неявні згадки в потоці, тож бот відповідає лише на явні згадки `@bot` усередині потоків, навіть якщо бот уже брав участь у потоці. Без цього відповіді в потоці, де брав участь бот, обходять обмеження `requireMention`. -Елементи керування потоками відповідей: +Керування потоками відповідей: -- `channels.slack.replyToMode`: `off|first|all|batched` (за замовчуванням `off`) -- `channels.slack.replyToModeByChatType`: для `direct|group|channel` +- `channels.slack.replyToMode`: `off|first|all|batched` (типово `off`) +- `channels.slack.replyToModeByChatType`: для кожного з `direct|group|channel` - застарілий резервний варіант для прямих чатів: `channels.slack.dm.replyToMode` -Підтримуються ручні теги відповідей: +Підтримуються ручні теги відповіді: - `[[reply_to_current]]` - `[[reply_to:]]` -Примітка: `replyToMode="off"` вимикає **усі** потоки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все одно враховуються в режимі `"off"`. Відмінність відображає моделі потоків на платформах: у Slack потоки приховують повідомлення від каналу, тоді як у Telegram відповіді залишаються видимими в основному потоці чату. +Примітка: `replyToMode="off"` вимикає **усі** потоки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"`. Різниця відображає моделі потоків на платформах: у Slack потоки приховують повідомлення від каналу, тоді як у Telegram відповіді залишаються видимими в основному потоці чату. ## Реакції підтвердження -`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. +`ackReaction` надсилає emoji-підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: @@ -730,28 +730,29 @@ openclaw gateway Примітки: -- Slack очікує короткі коди (наприклад, `"eyes"`). +- Slack очікує shortcodes (наприклад, `"eyes"`). - Використовуйте `""`, щоб вимкнути реакцію для облікового запису Slack або глобально. ## Потокова передача тексту -`channels.slack.streaming` керує поведінкою живого попереднього перегляду: +`channels.slack.streaming` керує поведінкою попереднього перегляду в реальному часі: -- `off`: вимкнути потокову трансляцію живого попереднього перегляду. -- `partial` (за замовчуванням): замінювати текст попереднього перегляду останнім частковим виводом. +- `off`: вимкнути потокову передачу попереднього перегляду в реальному часі. +- `partial` (типово): замінювати текст попереднього перегляду останнім частковим виводом. - `block`: додавати фрагментовані оновлення попереднього перегляду. - `progress`: показувати текст статусу прогресу під час генерації, а потім надсилати фінальний текст. -- `streaming.preview.toolProgress`: коли активний чорновий попередній перегляд, спрямовувати оновлення інструментів/прогресу в те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`). Встановіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу. +- `streaming.preview.toolProgress`: коли активний чернетковий попередній перегляд, спрямовувати оновлення інструментів/прогресу в те саме редаговане повідомлення попереднього перегляду (типово: `true`). Установіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу. -`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (за замовчуванням: `true`). +`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`). -- Для нативної потокової передачі тексту та появи статусу потоку помічника Slack має бути доступний потік відповіді. Вибір потоку, як і раніше, підпорядковується `replyToMode`. -- Кореневі повідомлення каналів і групових чатів усе ще можуть використовувати звичайний чорновий попередній перегляд, коли нативна потокова передача недоступна. -- Приватні повідомлення Slack верхнього рівня за замовчуванням залишаються поза потоками, тому вони не показують попередній перегляд у стилі потоку; використовуйте відповіді в потоках або `typingReaction`, якщо хочете бачити прогрес там. +- Для нативної потокової передачі тексту та відображення статусу потоку Slack assistant має бути доступний потік відповіді. Вибір потоку й надалі підпорядковується `replyToMode`. +- Кореневі повідомлення каналів і групових чатів усе ще можуть використовувати звичайний чернетковий попередній перегляд, коли нативна потокова передача недоступна. +- Slack DM верхнього рівня типово залишаються поза потоками, тому не показують попередній перегляд у стилі потоку; використовуйте відповіді в потоках або `typingReaction`, якщо хочете бачити прогрес там. - Медіа та нетекстові корисні навантаження повертаються до звичайної доставки. -- Якщо потокова передача збивається посеред відповіді, OpenClaw повертається до звичайної доставки для решти корисних навантажень. +- Фінальні медіа/помилки скасовують відкладені редагування попереднього перегляду без скидання тимчасової чернетки; придатні фінальні текстові/block-відповіді скидаються лише тоді, коли можуть відредагувати попередній перегляд на місці. +- Якщо потокова передача збоїть посеред відповіді, OpenClaw повертається до звичайної доставки для решти корисних навантажень. -Використовуйте чорновий попередній перегляд замість нативної потокової передачі тексту Slack: +Використовуйте чернетковий попередній перегляд замість нативної потокової передачі тексту Slack: ```json5 { @@ -768,13 +769,13 @@ openclaw gateway Застарілі ключі: -- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрує до `channels.slack.streaming.mode`. -- булеве значення `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. -- застарілий `channels.slack.nativeStreaming` автоматично мігрує до `channels.slack.streaming.nativeTransport`. +- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрується до `channels.slack.streaming.mode`. +- булевий `channels.slack.streaming` автоматично мігрується до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. +- застарілий `channels.slack.nativeStreaming` автоматично мігрується до `channels.slack.streaming.nativeTransport`. -## Резервна реакція набору тексту +## Резервний варіант реакції друку -`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в потоках, де використовується стандартний індикатор стану "is typing...". +`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в потоках, де використовується типовий індикатор стану "is typing...". Порядок визначення: @@ -783,40 +784,40 @@ openclaw gateway Примітки: -- Slack очікує короткі коди (наприклад, `"hourglass_flowing_sand"`). -- Реакція застосовується за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або шляху помилки. +- Slack очікує shortcodes (наприклад, `"hourglass_flowing_sand"`). +- Реакція надсилається за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або сценарію помилки. -## Медіа, фрагментація та доставка +## Медіа, розбиття на частини та доставка Вкладення файлів Slack завантажуються з приватних URL-адрес, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, якщо отримання успішне та дозволяють обмеження розміру. - Обмеження розміру вхідних даних під час виконання за замовчуванням становить `20MB`, якщо не перевизначено через `channels.slack.mediaMaxMb`. + Типове обмеження розміру вхідних даних під час виконання — `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`. - - текстові фрагменти використовують `channels.slack.textChunkLimit` (за замовчуванням 4000) + - текстові частини використовують `channels.slack.textChunkLimit` (типово 4000) - `channels.slack.chunkMode="newline"` вмикає розбиття спочатку за абзацами - надсилання файлів використовує API завантаження Slack і може включати відповіді в потоках (`thread_ts`) - - обмеження вихідних медіа дотримується `channels.slack.mediaMaxMb`, якщо його налаштовано; інакше надсилання в канал використовує типові значення MIME-kind з конвеєра медіа + - обмеження для вихідних медіа визначається `channels.slack.mediaMaxMb`, якщо налаштовано; інакше надсилання через канал використовує типові значення MIME-kind з медіапайплайна Бажані явні цілі: - - `user:` для приватних повідомлень + - `user:` для DM - `channel:` для каналів - Приватні повідомлення Slack відкриваються через API розмов Slack під час надсилання до цілей користувача. + Slack DM відкриваються через API бесід Slack під час надсилання до цілей користувача. -## Команди та поведінка slash-команд +## Команди та поведінка слеш-команд -Slash-команди відображаються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити параметри команд за замовчуванням: +Слеш-команди відображаються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команд: - `enabled: false` - `name: "openclaw"` @@ -827,30 +828,30 @@ Slash-команди відображаються в Slack або як одна /openclaw /help ``` -Нативні команди потребують [додаткових налаштувань маніфесту](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях. +Нативні команди потребують [додаткових параметрів маніфесту](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або натомість `commands.native: true` у глобальних конфігураціях. -- Автоматичний режим нативних команд **вимкнено** для Slack, тому `commands.native: "auto"` не вмикає нативні команди Slack. +- Автоматичний режим нативних команд для Slack **вимкнено**, тому `commands.native: "auto"` не вмикає нативні команди Slack. ```txt /help ``` -Нативні меню аргументів використовують адаптивну стратегію відображення, яка показує модальне вікно підтвердження перед передаванням вибраного значення параметра: +Нативні меню аргументів використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед надсиланням вибраного значення параметра: - до 5 параметрів: блоки кнопок -- 6-100 параметрів: статичне меню вибору -- понад 100 параметрів: зовнішній вибір з асинхронною фільтрацією параметрів, коли доступні обробники параметрів інтерактивності +- 6–100 параметрів: статичне меню вибору +- понад 100 параметрів: зовнішній вибір з асинхронною фільтрацією параметрів, коли доступні обробники параметрів interactivity - перевищено обмеження Slack: закодовані значення параметрів повертаються до кнопок ```txt /think ``` -Сесії slash-команд використовують ізольовані ключі на кшталт `agent::slack:slash:` і все одно маршрутизують виконання команд до цільової сесії розмови через `CommandTargetSessionKey`. +Сесії слеш-команд використовують ізольовані ключі на зразок `agent::slack:slash:` і все одно маршрутизують виконання команд до цільової сесії бесіди за допомогою `CommandTargetSessionKey`. ## Інтерактивні відповіді -Slack може відображати інтерактивні елементи керування відповідями, створеними агентом, але цю функцію за замовчуванням вимкнено. +Slack може рендерити інтерактивні елементи відповіді, створені агентом, але ця можливість типово вимкнена. Увімкніть її глобально: @@ -866,7 +867,7 @@ Slack може відображати інтерактивні елементи } ``` -Або увімкніть лише для одного облікового запису Slack: +Або увімкніть її лише для одного облікового запису Slack: ```json5 { @@ -884,7 +885,7 @@ Slack може відображати інтерактивні елементи } ``` -Коли функцію увімкнено, агенти можуть створювати директиви відповідей лише для Slack: +Коли можливість увімкнена, агенти можуть видавати директиви відповідей лише для Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` @@ -893,33 +894,32 @@ Slack може відображати інтерактивні елементи Примітки: -- Це інтерфейс користувача, специфічний для Slack. Інші канали не перетворюють директиви Slack Block Kit у власні системи кнопок. -- Значення інтерактивних зворотних викликів — це непрозорі токени, згенеровані OpenClaw, а не сирі значення, створені агентом. -- Якщо згенеровані інтерактивні блоки перевищують обмеження Slack Block Kit, OpenClaw повертається до оригінальної текстової відповіді замість надсилання некоректного payload блоків. +- Це UI, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок. +- Значення інтерактивних callback — це непрозорі токени, згенеровані OpenClaw, а не сирі значення, створені агентом. +- Якщо згенеровані інтерактивні блоки перевищують обмеження Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання некоректного корисного навантаження blocks. ## Підтвердження exec у Slack Slack може працювати як нативний клієнт підтвердження з інтерактивними кнопками та взаємодіями, замість повернення до Web UI або термінала. -- Для нативної маршрутизації в DM/каналах підтвердження exec використовують `channels.slack.execApprovals.*`. -- Підтвердження Plugin також можуть оброблятися через ту саму Slack-native поверхню кнопок, коли запит уже надходить у Slack і тип id підтвердження — `plugin:`. -- Авторизація затверджувача, як і раніше, примусово перевіряється: лише користувачі, визначені як затверджувачі, можуть схвалювати або відхиляти запити через Slack. +- Підтвердження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналу. +- Підтвердження Plugin так само можуть вирішуватися через ту саму нативну поверхню кнопок Slack, коли запит уже надходить у Slack, а тип ідентифікатора підтвердження — `plugin:`. +- Авторизація затверджувача все одно застосовується: лише користувачі, ідентифіковані як затверджувачі, можуть підтверджувати або відхиляти запити через Slack. -Для цього використовується та сама спільна поверхня кнопок підтвердження, що й в інших каналах. Коли в налаштуваннях вашого застосунку Slack увімкнено `interactivity`, запити на підтвердження відображаються як кнопки Block Kit безпосередньо в розмові. +Це використовує ту саму спільну поверхню кнопок підтвердження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на підтвердження рендеряться як кнопки Block Kit безпосередньо в бесіді. Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw -має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що -підтвердження в чаті недоступні або єдиним шляхом є ручне підтвердження. +має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що підтвердження в чаті недоступні або ручне підтвердження є єдиним шляхом. Шлях конфігурації: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (необов’язково; за можливості використовується резервний варіант `commands.ownerAllowFrom`) -- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) +- `channels.slack.execApprovals.approvers` (необов’язково; повертається до `commands.ownerAllowFrom`, коли можливо) +- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter` -Slack автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"` і розпізнається принаймні один -затверджувач. Встановіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт підтвердження. -Встановіть `enabled: true`, щоб примусово ввімкнути нативні підтвердження, коли затверджувачів розпізнано. +Slack автоматично вмикає нативні підтвердження exec, коли `enabled` не встановлено або має значення `"auto"` і визначено принаймні одного +затверджувача. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт підтвердження. +Установіть `enabled: true`, щоб примусово ввімкнути нативні підтвердження, коли затверджувачі визначаються. Типова поведінка без явної конфігурації підтверджень exec для Slack: @@ -931,8 +931,8 @@ Slack автоматично вмикає нативні підтверджен } ``` -Явна Slack-native конфігурація потрібна лише тоді, коли ви хочете перевизначити затверджувачів, додати фільтри або -вибрати доставку в чат походження: +Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити затверджувачів, додати фільтри або +використовувати доставку до чату-джерела: ```json5 { @@ -949,49 +949,49 @@ Slack автоматично вмикає нативні підтверджен ``` Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити на підтвердження exec також мають -маршрутизуватися до інших чатів або явних позасмугових цілей. Спільне переспрямування `approvals.plugin` також є -окремим; Slack-native кнопки все одно можуть обробляти підтвердження plugin, коли ці запити вже надходять +маршрутизуватися до інших чатів або явних позасмугових цілей. Спільне переспрямування `approvals.plugin` також +окреме; нативні кнопки Slack все одно можуть вирішувати підтвердження plugin, коли ці запити вже надходять у Slack. -`/approve` у тому самому чаті також працює в каналах і DM Slack, які вже підтримують команди. Див. [Exec approvals](/uk/tools/exec-approvals) для повної моделі переспрямування підтверджень. +`/approve` у тому самому чаті також працює в каналах і DM Slack, які вже підтримують команди. Див. [Підтвердження exec](/uk/tools/exec-approvals) для повної моделі переспрямування підтверджень. ## Події та операційна поведінка -- Редагування/видалення повідомлень і трансляції потоків відображаються в системні події. -- Події додавання/видалення реакцій відображаються в системні події. -- Події приєднання/виходу учасника, створення/перейменування каналу та додавання/видалення закріплень відображаються в системні події. -- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли ввімкнено `configWrites`. +- Редагування/видалення повідомлень/розсилки потоків зіставляються із системними подіями. +- Події додавання/видалення реакцій зіставляються із системними подіями. +- Події приєднання/виходу учасників, створення/перейменування каналів і додавання/видалення закріплень зіставляються із системними подіями. +- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли увімкнено `configWrites`. - Метадані теми/призначення каналу вважаються недовіреним контекстом і можуть бути впроваджені в контекст маршрутизації. -- Ініціатор потоку та початкове заповнення контексту історії потоку фільтруються за налаштованими allowlist відправників, коли це застосовно. -- Дії блоків і взаємодії з модальними вікнами створюють структуровані системні події `Slack interaction: ...` з розширеними полями payload: - - дії блоків: вибрані значення, мітки, значення picker та метадані `workflow_*` +- Початкове повідомлення потоку та початкове наповнення контексту історії потоку фільтруються за налаштованими allowlist відправників, коли це застосовно. +- Дії blocks і взаємодії модальних вікон генерують структуровані системні події `Slack interaction: ...` з насиченими полями корисного навантаження: + - дії blocks: вибрані значення, мітки, значення picker і метадані `workflow_*` - події модальних вікон `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеними даними форми -## Вказівники на довідник з конфігурації +## Вказівники на довідник конфігурації Основний довідник: -- [Довідник з конфігурації - Slack](/uk/gateway/configuration-reference#slack) +- [Довідник конфігурації - Slack](/uk/gateway/configuration-reference#slack) - Високосигнальні поля Slack: + Ключові поля Slack: - режим/автентифікація: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - доступ до DM: `dm.enabled`, `dmPolicy`, `allowFrom` (застаріле: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний варіант; залишайте вимкненим, якщо не потрібно) - - доступ до каналів: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний; тримайте вимкненим, якщо немає потреби) + - доступ до каналу: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - потоки/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - операції/можливості: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` -## Усунення неполадок +## Усунення проблем - Перевіряйте в такому порядку: + Перевірте в такому порядку: - `groupPolicy` - allowlist каналів (`channels.slack.channels`) - `requireMention` - - allowlist `users` для кожного каналу + - allowlist `users` для конкретного каналу Корисні команди: @@ -1008,7 +1008,7 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`) - - підтвердження зв’язування / записи allowlist + - підтвердження прив’язування / записи allowlist ```bash openclaw pairing list slack @@ -1016,13 +1016,13 @@ openclaw pairing list slack - - Перевірте токени бота й застосунку, а також увімкнення Socket Mode в налаштуваннях застосунку Slack. + + Перевірте токени бота + застосунку та ввімкнення Socket Mode в налаштуваннях застосунку Slack. Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або `appTokenStatus: "configured_unavailable"`, обліковий запис Slack налаштований, але поточне середовище виконання не змогло визначити значення, - що підтримується SecretRef. + що стоїть за SecretRef. @@ -1030,21 +1030,21 @@ openclaw pairing list slack Перевірте: - signing secret - - шлях Webhook + - шлях webhook - URL-адреси запитів Slack (Events + Interactivity + Slash Commands) - унікальний `webhookPath` для кожного HTTP-облікового запису Якщо `signingSecretStatus: "configured_unavailable"` з’являється у знімках - облікового запису, HTTP-обліковий запис налаштований, але поточне середовище виконання не змогло - визначити signing secret, що підтримується SecretRef. + облікових записів, HTTP-обліковий запис налаштований, але поточне середовище виконання не змогло + визначити signing secret, що стоїть за SecretRef. - Перевірте, який варіант ви планували використовувати: + Перевірте, чи ви мали на увазі: - - режим нативних команд (`channels.slack.commands.native: true`) з відповідними slash-командами, зареєстрованими в Slack - - або режим однієї slash-команди (`channels.slack.slashCommand.enabled: true`) + - режим нативних команд (`channels.slack.commands.native: true`) з відповідними зареєстрованими в Slack слеш-командами + - або режим однієї слеш-команди (`channels.slack.slashCommand.enabled: true`) Також перевірте `commands.useAccessGroups` і allowlist каналів/користувачів. @@ -1053,10 +1053,10 @@ openclaw pairing list slack ## Пов’язане -- [Зв’язування](/uk/channels/pairing) +- [Прив’язування](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Безпека](/uk/gateway/security) - [Маршрутизація каналів](/uk/channels/channel-routing) -- [Усунення неполадок](/uk/channels/troubleshooting) +- [Усунення проблем](/uk/channels/troubleshooting) - [Конфігурація](/uk/gateway/configuration) -- [Slash-команди](/uk/tools/slash-commands) +- [Слеш-команди](/uk/tools/slash-commands) diff --git a/docs/uk/concepts/streaming.md b/docs/uk/concepts/streaming.md index 235d95c32..19fa3e02f 100644 --- a/docs/uk/concepts/streaming.md +++ b/docs/uk/concepts/streaming.md @@ -1,184 +1,192 @@ --- read_when: - - Пояснення того, як streaming або chunking працює в каналах - - Зміна поведінки блокового streaming або chunking каналу - - Налагодження дублікатів або передчасних блокових відповідей чи потокового передавання попереднього перегляду каналу -summary: Поведінка streaming + chunking (блокові відповіді, потокове передавання попереднього перегляду каналу, зіставлення режимів) -title: Streaming і Chunking + - Пояснення того, як потокова передача або розбиття на фрагменти працює в каналах + - Зміна поведінки блокової потокової передачі або розбиття каналу на фрагменти + - Налагодження дубльованих/передчасних блокових відповідей або потокової передачі попереднього перегляду каналу +summary: Поведінка потокової передачі + розбиття на фрагменти (блокові відповіді, потокова передача попереднього перегляду каналу, зіставлення режимів) +title: Потокова передача та розбиття на фрагменти x-i18n: - generated_at: "2026-04-21T20:52:30Z" + generated_at: "2026-04-22T01:34:44Z" model: gpt-5.4 provider: openai - source_hash: e550c13ce180bf8f72fced4071926bfe8d24dfb1a419c19c51a64eb9ff216ff1 + source_hash: c6b246025ea1b1be57705bde60c0cdb485ffda727392cf00ea5a165571e37fce source_path: concepts/streaming.md workflow: 15 --- -# Streaming + chunking +# Потокова передача + розбиття на фрагменти -OpenClaw має два окремі рівні streaming: +OpenClaw має два окремі рівні потокової передачі: -- **Блокове streaming (канали):** надсилає завершені **блоки**, поки асистент пише. Це звичайні повідомлення каналу (не дельти токенів). -- **Streaming попереднього перегляду (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації. +- **Блокова потокова передача (канали):** надсилає завершені **блоки**, поки асистент пише. Це звичайні повідомлення каналу (не дельти токенів). +- **Потокова передача попереднього перегляду (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації. -Справжнього streaming дельт токенів до повідомлень каналу сьогодні **немає**. Streaming попереднього перегляду є повідомлення-орієнтованим (надсилання + редагування/додавання). +Справжньої потокової передачі дельт токенів у повідомлення каналу наразі **немає**. Потокова передача попереднього перегляду базується на повідомленнях (надсилання + редагування/додавання). -## Блокове streaming (повідомлення каналу) +## Блокова потокова передача (повідомлення каналу) -Блокове streaming надсилає вивід асистента грубими порціями, щойно він стає доступним. +Блокова потокова передача надсилає вихідні дані асистента великими фрагментами в міру їхньої доступності. ``` -Вивід моделі +Вихід моделі └─ text_delta/events ├─ (blockStreamingBreak=text_end) - │ └─ chunker надсилає блоки, коли буфер зростає + │ └─ chunker надсилає блоки в міру зростання буфера └─ (blockStreamingBreak=message_end) - └─ chunker скидає вміст на message_end - └─ надсилання каналу (блокові відповіді) + └─ chunker скидає дані на message_end + └─ надсилання в канал (блокові відповіді) ``` -Легенда: +Умовні позначення: -- `text_delta/events`: події потоку моделі (можуть бути нечастими для моделей без streaming). -- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + пріоритет розриву. +- `text_delta/events`: події потоку моделі (можуть бути рідкісними для моделей без потокової передачі). +- `chunker`: `EmbeddedBlockChunker`, який застосовує мінімальні/максимальні межі + пріоритет розривів. - `channel send`: фактичні вихідні повідомлення (блокові відповіді). **Керування:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (типово вимкнено). -- Перевизначення каналу: `*.blockStreaming` (і варіанти для окремого акаунта), щоб примусово встановити `"on"`/`"off"` для кожного каналу. +- Перевизначення каналу: `*.blockStreaming` (і варіанти для окремих акаунтів), щоб примусово встановити `"on"`/`"off"` для кожного каналу. - `agents.defaults.blockStreamingBreak`: `"text_end"` або `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднує streamed-блоки перед надсиланням). +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднання потокових блоків перед надсиланням). - Жорстке обмеження каналу: `*.textChunkLimit` (наприклад, `channels.whatsapp.textChunkLimit`). -- Режим chunking каналу: `*.chunkMode` (`length` типово, `newline` розбиває за порожніми рядками (межами абзаців) перед chunking за довжиною). -- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (типово 17) розбиває високі відповіді, щоб уникнути обрізання в UI. +- Режим розбиття каналу: `*.chunkMode` (`length` типово, `newline` розбиває за порожніми рядками (межами абзаців) перед розбиттям за довжиною). +- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (типово 17) розбиває високі відповіді, щоб уникнути обрізання в інтерфейсі. **Семантика меж:** -- `text_end`: передавати блоки, щойно їх надсилає chunker; скидати на кожному `text_end`. -- `message_end`: чекати, доки повідомлення асистента завершиться, а потім скидати буферизований вивід. +- `text_end`: передавати блоки в потоці, щойно `chunker` їх видає; скидати на кожному `text_end`. +- `message_end`: чекати, поки повідомлення асистента завершиться, а потім скидати буферизований вміст. -`message_end` усе одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому наприкінці він може надсилати кілька chunk. +`message_end` усе одно використовує `chunker`, якщо буферизований текст перевищує `maxChars`, тому наприкінці він може видати кілька фрагментів. -## Алгоритм chunking (нижня/верхня межі) +## Алгоритм розбиття на фрагменти (нижня/верхня межа) -Блоковий chunking реалізовано в `EmbeddedBlockChunker`: +Розбиття блоків реалізоване в `EmbeddedBlockChunker`: - **Нижня межа:** не надсилати, доки буфер < `minChars` (якщо не примусово). -- **Верхня межа:** віддавати перевагу розривам перед `maxChars`; якщо примусово, розбивати на `maxChars`. -- **Пріоритет розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. -- **Огорожі коду:** ніколи не розбивати всередині огорож; якщо примусово на `maxChars`, закривати + знову відкривати огорожу, щоб Markdown залишався валідним. +- **Верхня межа:** віддавати перевагу розривам до `maxChars`; якщо примусово, розривати на `maxChars`. +- **Пріоритет розривів:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. +- **Блоки коду:** ніколи не розривати всередині блоків; якщо примусово розривати на `maxChars`, закривати й знову відкривати блок, щоб зберегти коректність Markdown. -`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити ліміти конкретного каналу не можна. +`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити ліміти конкретного каналу неможливо. -## Coalescing (об’єднання streamed-блоків) +## Об’єднання (злиття потокових блоків) -Коли блокове streaming увімкнено, OpenClaw може **об’єднувати послідовні блокові chunk** -перед їх надсиланням. Це зменшує «спам із одного рядка», водночас зберігаючи +Коли блокова потокова передача ввімкнена, OpenClaw може **об’єднувати послідовні блокові фрагменти** +перед їхнім надсиланням. Це зменшує «спам з одного рядка», водночас зберігаючи поступове виведення. -- Coalescing чекає **пауз бездіяльності** (`idleMs`) перед скиданням. -- Буфери обмежуються `maxChars` і скидаються, якщо перевищують його. -- `minChars` запобігає надсиланню крихітних фрагментів, доки не накопичиться достатньо тексту - (остаточне скидання завжди надсилає решту тексту). -- Об’єднувач визначається з `blockStreamingChunk.breakPreference` +- Об’єднання чекає **пауз простою** (`idleMs`) перед скиданням. +- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать це значення. +- `minChars` не дає надсилати надто дрібні фрагменти, доки не накопичиться достатньо тексту + (остаточне скидання завжди надсилає залишковий текст). +- Роздільник визначається з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл). -- Перевизначення для каналу доступні через `*.blockStreamingCoalesce` (включно з конфігураціями для окремих акаунтів). -- Типове значення coalesce `minChars` підвищується до 1500 для Signal/Slack/Discord, якщо не перевизначено. +- Перевизначення для каналів доступні через `*.blockStreamingCoalesce` (зокрема для конфігурацій окремих акаунтів). +- Типове значення `minChars` для об’єднання підвищується до 1500 для Signal/Slack/Discord, якщо його не перевизначено. -## Природне сповільнення між блоками +## Людиноподібні паузи між блоками -Коли блокове streaming увімкнено, можна додати **випадкову паузу** між -блоковими відповідями (після першого блока). Це робить відповіді з кількох бульбашок +Коли блокова потокова передача ввімкнена, можна додати **випадкову паузу** між +блоковими відповідями (після першого блоку). Це робить відповіді з кількох бульбашок природнішими. -- Конфігурація: `agents.defaults.humanDelay` (перевизначається для агента через `agents.list[].humanDelay`). -- Режими: `off` (типово), `natural` (800–2500 мс), `custom` (`minMs`/`maxMs`). -- Застосовується лише до **блокових відповідей**, а не до фінальних відповідей чи зведень інструментів. +- Конфігурація: `agents.defaults.humanDelay` (перевизначення для агента через `agents.list[].humanDelay`). +- Режими: `off` (типово), `natural` (800–2500мс), `custom` (`minMs`/`maxMs`). +- Застосовується лише до **блокових відповідей**, а не до фінальних відповідей чи підсумків інструментів. -## «Stream chunks або все одразу» +## «Передавати фрагменти в потоці чи все цілком» -Це зіставляється так: +Це відповідає таким варіантам: -- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (надсилати в процесі). Для каналів, окрім Telegram, також потрібне `*.blockStreaming: true`. -- **Stream everything at end:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо, кількома chunk, якщо дуже довго). -- **Без блокового streaming:** `blockStreamingDefault: "off"` (лише фінальна відповідь). +- **Передавати фрагменти в потоці:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (надсилати в міру готовності). Для каналів, відмінних від Telegram, також потрібне `*.blockStreaming: true`. +- **Передати все наприкінці:** `blockStreamingBreak: "message_end"` (одноразове скидання, можливо, кількома фрагментами, якщо відповідь дуже довга). +- **Без блокової потокової передачі:** `blockStreamingDefault: "off"` (лише фінальна відповідь). -**Примітка щодо каналів:** Блокове streaming **вимкнено, якщо тільки** +**Примітка щодо каналів:** Блокова потокова передача **вимкнена, доки** `*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд (`channels..streaming`) без блокових відповідей. -Нагадування щодо розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в корені конфігурації. +Нагадування про розташування конфігурації: типові значення `blockStreaming*` розміщені в `agents.defaults`, а не в кореневій конфігурації. -## Режими streaming попереднього перегляду +## Режими потокової передачі попереднього перегляду Канонічний ключ: `channels..streaming` Режими: -- `off`: вимкнути streaming попереднього перегляду. +- `off`: вимкнути потокову передачу попереднього перегляду. - `partial`: один попередній перегляд, який замінюється найновішим текстом. -- `block`: попередній перегляд оновлюється chunk-ами або кроками додавання. +- `block`: попередній перегляд оновлюється кроками з розбиттям на фрагменти/додаванням. - `progress`: попередній перегляд прогресу/статусу під час генерації, фінальна відповідь після завершення. -### Зіставлення каналів +### Відповідність каналів -| Канал | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | ----------------- | +| Канал | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ------------------ | | Telegram | ✅ | ✅ | ✅ | зіставляється з `partial` | | Discord | ✅ | ✅ | ✅ | зіставляється з `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | Лише для Slack: -- `channels.slack.streaming.nativeTransport` перемикає нативні виклики Slack streaming API, коли `channels.slack.streaming.mode="partial"` (типово: `true`). -- Нативне streaming Slack і статус потоків помічника Slack потребують цільового потоку відповіді; DM верхнього рівня не показують такий попередній перегляд у стилі потоку. +- `channels.slack.streaming.nativeTransport` перемикає виклики рідного API потокової передачі Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`). +- Рідна потокова передача Slack і статус потоку помічника Slack потребують цільового потоку відповідей; DM верхнього рівня не показують такий попередній перегляд у стилі потоку. Міграція застарілих ключів: -- Telegram: `streamMode` + булеве `streaming` автоматично мігрують до enum `streaming`. -- Discord: `streamMode` + булеве `streaming` автоматично мігрують до enum `streaming`. -- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булеве `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застаріле `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`. +- Telegram: `streamMode` + булеве `streaming` автоматично мігрують у enum `streaming`. +- Discord: `streamMode` + булеве `streaming` автоматично мігрують у enum `streaming`. +- Slack: `streamMode` автоматично мігрує в `streaming.mode`; булеве `streaming` автоматично мігрує в `streaming.mode` плюс `streaming.nativeTransport`; застаріле `nativeStreaming` автоматично мігрує в `streaming.nativeTransport`. ### Поведінка під час виконання Telegram: - Використовує оновлення попереднього перегляду через `sendMessage` + `editMessageText` у DM, групах і темах. -- Streaming попереднього перегляду пропускається, коли блокове streaming Telegram явно увімкнено (щоб уникнути подвійного streaming). +- Потокова передача попереднього перегляду пропускається, коли блокова потокова передача Telegram явно ввімкнена (щоб уникнути подвійної потокової передачі). - `/reasoning stream` може записувати міркування в попередній перегляд. Discord: -- Використовує повідомлення попереднього перегляду через надсилання + редагування. -- Режим `block` використовує draft chunking (`draftChunk`). -- Streaming попереднього перегляду пропускається, коли блокове streaming Discord явно увімкнено. +- Використовує надсилання + редагування повідомлень попереднього перегляду. +- Режим `block` використовує розбиття чернетки (`draftChunk`). +- Потокова передача попереднього перегляду пропускається, коли блокова потокова передача Discord явно ввімкнена. +- Фінальні медіа, помилки та явні корисні навантаження відповіді скасовують відкладені попередні перегляди без скидання нової чернетки, а потім використовують звичайне доставлення. Slack: -- `partial` може використовувати нативне streaming Slack (`chat.startStream`/`append`/`stop`), коли воно доступне. -- `block` використовує попередні перегляди чернетки у стилі додавання. +- `partial` може використовувати рідну потокову передачу Slack (`chat.startStream`/`append`/`stop`), коли вона доступна. +- `block` використовує попередні перегляди чернеток у стилі додавання. - `progress` використовує текст попереднього перегляду статусу, а потім фінальну відповідь. +- Фінальні корисні навантаження медіа/помилки та фінали прогресу не створюють тимчасових повідомлень-чернеток; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають відкладений текст чернетки. Mattermost: -- Передає thinking, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надсилати. -- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний під час фіналізації. +- Передає міркування, активність інструментів і частковий текст відповіді в одному чернетковому повідомленні попереднього перегляду, яке фіналізується на місці, коли фінальну відповідь безпечно надсилати. +- Повертається до надсилання нового фінального повідомлення, якщо повідомлення попереднього перегляду було видалено або воно інакше недоступне під час фіналізації. +- Фінальні корисні навантаження медіа/помилки скасовують відкладені оновлення попереднього перегляду перед звичайним доставленням замість скидання тимчасового повідомлення попереднього перегляду. + +Matrix: + +- Попередні перегляди чернеток фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. +- Фінали лише з медіа, помилки та фінали з невідповідністю цільової відповіді скасовують відкладені оновлення попереднього перегляду перед звичайним доставленням; уже видимий застарілий попередній перегляд редагується. ### Оновлення попереднього перегляду прогресу інструментів -Streaming попереднього перегляду також може включати оновлення **tool-progress** — короткі рядки стану на кшталт "searching the web", "reading file" або "calling tool", — які з’являються в тому самому повідомленні попереднього перегляду, поки інструменти працюють, ще до фінальної відповіді. Це робить багатокрокові ходи з інструментами візуально активними, а не мовчазними між першим thinking-попереднім переглядом і фінальною відповіддю. +Потокова передача попереднього перегляду також може включати оновлення **прогресу інструментів** — короткі рядки статусу на кшталт «пошук у вебі», «читання файлу» або «виклик інструмента», які з’являються в тому самому повідомленні попереднього перегляду під час роботи інструментів, ще до фінальної відповіді. Це робить багатоетапні ходи з інструментами візуально живими, а не мовчазними між першим попереднім переглядом міркування та фінальною відповіддю. Підтримувані поверхні: -- **Discord**, **Slack** і **Telegram** передають tool-progress у редагування живого попереднього перегляду. -- **Mattermost** уже вбудовує активність інструментів у свій єдиний чернетковий допис попереднього перегляду (див. вище). -- Редагування tool-progress дотримуються активного режиму streaming попереднього перегляду; вони пропускаються, коли streaming попереднього перегляду має значення `off` або коли блокове streaming уже перебрало керування повідомленням. +- **Discord**, **Slack** і **Telegram** передають прогрес інструментів у живе редагування попереднього перегляду. +- **Mattermost** уже вбудовує активність інструментів у своє єдине чернеткове повідомлення попереднього перегляду (див. вище). +- Редагування прогресу інструментів дотримуються активного режиму потокової передачі попереднього перегляду; вони пропускаються, коли потокову передачу попереднього перегляду встановлено в `off` або коли блокова потокова передача вже перебрала керування повідомленням. ## Пов’язане -- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлень і доставка -- [Повторна спроба](/uk/concepts/retry) — поведінка повторної спроби при збої доставки -- [Канали](/uk/channels) — підтримка streaming для кожного каналу +- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлень і доставлення +- [Повторна спроба](/uk/concepts/retry) — поведінка повторних спроб у разі помилки доставлення +- [Канали](/uk/channels) — підтримка потокової передачі для окремих каналів diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 41515ce96..6c855523f 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -2,95 +2,95 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви оновлюєте plugin до сучасної архітектури plugin-ів - - Ви підтримуєте зовнішній plugin OpenClaw + - Ви оновлюєте Plugin до сучасної архітектури plugin + - Ви підтримуєте зовнішній Plugin OpenClaw sidebarTitle: Migrate to SDK summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-21T04:19:32Z" + generated_at: "2026-04-22T01:34:41Z" model: gpt-5.4 provider: openai - source_hash: d3d2ea9a8cc869b943ad774ac0ddb8828b80ce86432ece7b9aeed4f1edb30859 + source_hash: 72c9fc2d77f5feda336a1119fc42ebe088d5037f99c2b3843e9f06efed20386d source_path: plugins/sdk-migration.md workflow: 15 --- # Міграція Plugin SDK -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin-ів із цілеспрямованими, задокументованими імпортами. Якщо ваш plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система plugin-ів надавала дві широко відкриті поверхні, які дозволяли plugin-ам імпортувати все необхідне з однієї точки входу: +Стара система plugin надавала дві широкі поверхні, які дозволяли plugin імпортувати будь-що потрібне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних функцій. Його було запроваджено, щоб старіші hook-орієнтовані plugin-и продовжували працювати під час розробки нової архітектури plugin-ів. -- **`openclaw/extension-api`** — міст, який надавав plugin-ам прямий доступ до допоміжних засобів на боці хоста, наприклад до вбудованого засобу запуску агента. +- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші plugin на основі хуків продовжували працювати, поки будувалася нова архітектура plugin. +- **`openclaw/extension-api`** — міст, який надавав plugin прямий доступ до допоміжних засобів на боці хоста, таких як вбудований запускальник агентів. -Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові plugin-и не повинні їх використовувати, а наявні plugin-и слід мігрувати до того, як наступний мажорний випуск їх вилучить. +Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові plugin не повинні їх використовувати, а наявні plugin слід мігрувати до того, як наступний мажорний випуск їх видалить. - Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних випусків. - Plugin-и, які й надалі імпортують із цих поверхонь, перестануть працювати, коли це станеться. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних випусків. + Plugin, які досі імпортують із цих поверхонь, перестануть працювати, коли це станеться. ## Чому це змінилося Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних між собою модулів +- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних модулів - **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту -- **Неочевидна поверхня API** — не було способу визначити, які експорти є стабільними, а які — внутрішніми +- **Нечітка поверхня API** — не було способу визначити, які експорти є стабільними, а які — внутрішніми -Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. +Сучасний Plugin SDK вирішує цю проблему: кожен шлях імпорту (`openclaw/plugin-sdk/\`) є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні шви провайдерів для вбудованих каналів також зникли. Імпорти +Застарілі зручні шви provider для вбудованих каналів також прибрано. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -допоміжні шви з брендуванням каналів і +допоміжні шви під брендом каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями монорепозиторію, а не -стабільними контрактами plugin-ів. Натомість використовуйте вузькі узагальнені підшляхи SDK. Усередині робочого простору вбудованого plugin-а зберігайте допоміжні засоби, що належать провайдеру, у власному -`api.ts` або `runtime-api.ts` цього plugin-а. +стабільними контрактами plugin. Натомість використовуйте вузькі універсальні підшляхи SDK. Усередині робочого простору вбудованого plugin зберігайте допоміжні засоби, що належать provider, у власному +`api.ts` або `runtime-api.ts` цього plugin. -Поточні приклади вбудованих провайдерів: +Поточні приклади вбудованих provider: -- Anthropic зберігає допоміжні засоби потокової обробки, специфічні для Claude, у власному шві `api.ts` / +- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби для моделей за замовчуванням і конструктори realtime-провайдерів у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби для онбордингу/конфігурації у власному `api.ts` +- OpenAI зберігає конструктори provider, допоміжні засоби моделей за замовчуванням і конструктори provider реального часу у власному `api.ts` +- OpenRouter зберігає конструктор provider і допоміжні засоби онбордингу/конфігурації у власному + `api.ts` ## Як виконати міграцію - Channel plugin-и з підтримкою approval тепер надають нативну поведінку approval через - `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту середовища виконання. + Plugin каналів із підтримкою approval тепер надають нативну поведінку approval через + `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту runtime. - Основні зміни: + Ключові зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть auth/delivery, специфічні для approval, із застарілого зв’язування `plugin.auth` / - `plugin.approvals` до `approvalCapability` - - `ChannelPlugin.approvals` вилучено з публічного контракту channel plugin-а; + - Перенесіть специфічні для approval auth/delivery зі старої прив’язки `plugin.auth` / + `plugin.approvals` на `approvalCapability` + - `ChannelPlugin.approvals` було видалено з публічного контракту plugin каналу; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу з каналу; approval auth - hooks там більше не зчитуються ядром - - Реєструйте об’єкти середовища виконання, що належать каналу, як-от клієнти, токени або Bolt - apps, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте сповіщення про перенаправлення, що належать plugin-у, з нативних approval-обробників; - тепер ядро саме відповідає за routed-elsewhere сповіщення на основі фактичних результатів delivery - - Коли передаєте `channelRuntime` до `createChannelManager(...)`, надавайте - реальну поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. + - `plugin.auth` залишається лише для потоків входу/виходу каналу; хуки auth для approval + там більше не зчитуються ядром + - Реєструйте runtime-об’єкти, що належать каналу, такі як клієнти, токени або застосунки Bolt, + через `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте повідомлення reroute, що належать plugin, із нативних обробників approval; + тепер ядро відповідає за повідомлення про доставку в інше місце на основі фактичних результатів delivery + - Під час передавання `channelRuntime` до `createChannelManager(...)` надавайте + справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. - Див. `/plugins/sdk-channel-plugins`, щоб переглянути поточну - структуру можливостей approval. + Поточну структуру можливостей approval див. у `/plugins/sdk-channel-plugins`. - - Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows - wrappers `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. + + Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені обгортки Windows + `.cmd`/`.bat` тепер завершуються з закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. ```typescript // Before @@ -105,13 +105,13 @@ OpenClaw перейшов від широкого шару зворотної с }); ``` - Якщо ваш виклик не покладається навмисно на резервний перехід через shell, не встановлюйте - `allowShellFallback` і натомість обробляйте згенеровану помилку. + Якщо ваш виклик навмисно не покладається на резервний перехід до shell, не встановлюйте + `allowShellFallback` і натомість обробляйте викинуту помилку. - Знайдіть у своєму plugin-і імпорти з будь-якої застарілої поверхні: + Знайдіть у своєму plugin імпорти з будь-якої застарілої поверхні: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -120,8 +120,8 @@ OpenClaw перейшов від широкого шару зворотної с - - Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні зіставляється з певним сучасним шляхом імпорту: ```typescript // Before (deprecated backwards-compatibility layer) @@ -137,7 +137,7 @@ OpenClaw перейшов від широкого шару зворотної с import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на боці хоста використовуйте інжектоване середовище виконання plugin-а замість прямого імпорту: + Для допоміжних засобів на боці хоста використовуйте впроваджений runtime plugin замість прямого імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -148,7 +148,7 @@ OpenClaw перейшов від широкого шару зворотної с const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується й до інших допоміжних засобів застарілого моста: + Той самий шаблон застосовується й до інших застарілих допоміжних засобів bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -158,7 +158,7 @@ OpenClaw перейшов від широкого шару зворотної с | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | session store helpers | `api.runtime.agent.session.*` | + | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | @@ -173,184 +173,183 @@ OpenClaw перейшов від широкого шару зворотної с ## Довідник шляхів імпорту - | Import path | Призначення | Ключові експорти | + | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin-а | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/конструкторів точок входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий повторний експорт-парасолька для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цілеспрямовані визначення та конструктори точок входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори стану налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби середовища виконання під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Цільові визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити списку дозволених, конструктори статусу налаштування | + | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/гейтів дій облікових записів | + | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/гейта дій облікових записів | | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікових записів | Допоміжні засоби пошуку облікового запису + резервного значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби списку облікових записів/дій облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + резервного використання значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | Примітиви pairing для DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Префікс reply + wiring індикатора набору | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | Проводка префікса відповіді + індикатора набору | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація імен команд, обрізання описів, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політик груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідних envelope | Спільні допоміжні засоби маршрутизації + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних reply | Спільні допоміжні засоби запису та dispatch | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Допоміжні засоби статусу облікового запису та життєвого циклу чернеткового потоку | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки | + | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних відповідей | Спільні допоміжні засоби запису та диспетчеризації | | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Допоміжні засоби вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного середовища виконання | Допоміжні засоби outbound identity/send delegate і планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок thread | Допоміжні засоби життєвого циклу й адаптера прив’язок thread | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегата надсилання та планування payload | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби thread-binding | Допоміжні засоби життєвого циклу thread-binding та адаптерів | | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор media payload агента для застарілих макетів полів | - | `plugin-sdk/channel-runtime` | Застарілий шім сумісності | Лише застарілі утиліти середовища виконання каналу | - | `plugin-sdk/channel-send-result` | Типи результатів send | Типи результатів reply | - | `plugin-sdk/runtime-store` | Постійне сховище plugin-а | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання | Допоміжні засоби runtime/logging/backup/встановлення plugin-ів | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, timeout, retry та допоміжні засоби backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби середовища виконання plugin-а | Допоміжні засоби команд/hooks/http/interactive plugin-а | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | + | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | + | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, допоміжні засоби timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime plugin | Допоміжні засоби команд/хуків/http/interactive для plugin | | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра hook | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook | | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби process | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби середовища виконання CLI | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway та патчів стану каналу | + | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | + | `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Клієнт Gateway і допоміжні засоби патчів статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Стабільні при fallback допоміжні засоби перевірки команд Telegram, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби prompt approval | Допоміжні засоби payload exec/plugin approval, capability/profile approval, маршрутизації/середовища виконання native approval | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів approval | Payload approval exec/plugin, допоміжні засоби можливостей/профілю approval, нативні допоміжні засоби маршрутизації/runtime approval | | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби profile/filter native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби delivery для approval | Адаптери capability/delivery native approval | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілю/фільтра нативного approval exec | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби delivery для approval | Адаптери можливостей/delivery нативного approval | | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway для approval | Спільний допоміжний засіб визначення Gateway для approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження адаптера native approval для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби середовища виконання обробника approval; віддавайте перевагу вужчим швам adapter/gateway, якщо їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілі/облікового запису native approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply для approval | Допоміжні засоби payload reply exec/plugin approval | - | `plugin-sdk/channel-runtime-context` | Допоміжні засоби runtime-context каналу | Узагальнені допоміжні засоби register/get/watch для runtime-context каналу | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, DM gating, external-content і збирання секретів | + | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження нативного адаптера approval для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби runtime обробника approval; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби нативної прив’язки цілей/облікових записів approval | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповідей approval | Допоміжні засоби payload відповіді approval exec/plugin | + | `plugin-sdk/channel-runtime-context` | Допоміжні засоби контексту runtime каналу | Універсальні допоміжні засоби register/get/watch контексту runtime каналу | + | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, гейтінгу DM, зовнішнього вмісту та збору секретів | | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби середовища виконання SSRF | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy | | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичного gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби гейтінгу діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні засоби gating команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/command-status` | Візуалізатори статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Гейтинг команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | + | `plugin-sdk/command-status` | Рендерери статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільне середовище виконання reply | Inbound dispatch, Heartbeat, планувальник reply, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch reply | Допоміжні засоби finalize + dispatch провайдера | - | `plugin-sdk/reply-history` | Допоміжні засоби історії reply | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань reply | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk для reply | Допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідна диспетчеризація, Heartbeat, планувальник відповіді, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Допоміжні засоби finalize + диспетчеризації provider | + | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk відповіді | Допоміжні засоби chunking тексту/markdown | | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth | | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні засоби стану каналу | Конструктори зведення стану каналу/облікового запису, значення стану runtime за замовчуванням, допоміжні засоби метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби target resolver | + | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори зведень статусу каналу/облікового запису, значення стану runtime за замовчуванням, допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби визначення цілей | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягування рядкових URL із вхідних даних, подібних до request | - | `plugin-sdk/run-command` | Допоміжні засоби команд із часовими обмеженнями | Запускач команд із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Читачі параметрів | Загальні читачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування payload tool | Витягування нормалізованих payload з об’єктів результатів tool | - | `plugin-sdk/tool-send` | Витягування send tool | Витягування канонічних полів цілі send з аргументів tool | + | `plugin-sdk/request-url` | Допоміжні засоби URL запитів | Витягування рядкових URL із вхідних даних, подібних до запиту | + | `plugin-sdk/run-command` | Допоміжні засоби команд із таймером | Виконавець команд із таймером і нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів інструментів/CLI | + | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload з об’єктів результатів інструментів | + | `plugin-sdk/tool-send` | Витягування надсилання інструмента | Витягування канонічних полів цілі надсилання з аргументів інструмента | | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистеми та редагування | + | `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистеми та редагування чутливих даних | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload reply | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | Допоміжні засоби виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Цілеспрямовані допоміжні засоби налаштування OpenAI-сумісних self-hosted провайдерів | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth середовища виконання провайдера | Допоміжні засоби визначення API-ключа під час виконання | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth провайдера | Стандартний конструктор результату auth OAuth | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби env var провайдера | Допоміжні засоби пошуку env var auth провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики replay, допоміжні засоби endpoint провайдера та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу web-fetch провайдера | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search провайдера | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне зв’язування ввімкнення plugin-а | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/runtime web-search провайдера | - | `plugin-sdk/provider-tools` | Допоміжні засоби compat для tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics, а також допоміжні засоби compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби usage провайдера | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток stream провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Нативні допоміжні засоби транспорту провайдера, як-от guarded fetch, перетворення transport message і writable transport event streams | - | `plugin-sdk/keyed-async-queue` | Упорядкована async-черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби fetch/transform/store медіа, а також конструктори media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору candidate та повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдера media understanding, а також експорти допоміжних засобів зображень/аудіо для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування | + | `plugin-sdk/reply-payload` | Типи відповідей повідомлень | Типи payload відповідей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted provider | Допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted provider, сумісних з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime auth provider | Допоміжні засоби визначення API-ключів runtime | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключів provider | Допоміжні засоби онбордингу/запису профілю API-ключа | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth provider | Стандартний конструктор результату auth OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars provider | Допоміжні засоби пошуку env vars auth provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик replay, допоміжні засоби endpoint provider та нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі онбордингу provider | Допоміжні засоби конфігурації онбордингу | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Універсальні допоміжні засоби HTTP/можливостей endpoint provider | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/кешу provider web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search provider | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider, яким не потрібна прив’язка ввімкнення plugin | + | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search provider | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search provider | Допоміжні засоби реєстрації/кешу/runtime provider web-search | + | `plugin-sdk/provider-tools` | Допоміжні засоби compat інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні засоби usage provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби usage provider | + | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту provider | Нативні допоміжні засоби транспорту provider, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту з можливістю запису | + | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/збереження медіа, а також конструктори media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутні моделі для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні засоби Media understanding | Типи provider для media understanding, а також експорти допоміжних засобів зображення/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого асистенту тексту, допоміжні засоби рендерингу/chunking/таблиць markdown, редагування чутливих даних, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування | | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи провайдера мовлення, а також допоміжні засоби директив, реєстру й валідації для провайдерів | - | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдера мовлення, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime-транскрипції | Типи провайдера та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Допоміжні засоби realtime-голосу | Типи провайдера та допоміжні засоби реєстру | + | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи provider мовлення, а також допоміжні засоби директив, реєстру та валідації для provider | + | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи provider мовлення, реєстр, директиви, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в реальному часі | Типи provider і допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи provider і допоміжні засоби реєстру | | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, auth і допоміжні засоби реєстру | - | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних reply | Нормалізація/редукція payload інтерактивних reply | + | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи provider/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи provider/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей | | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви config-schema каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude channel plugin-а | - | `plugin-sdk/channel-status` | Допоміжні засоби стану каналу | Спільні допоміжні засоби snapshot/summary стану каналу | + | `plugin-sdk/channel-plugin-common` | Спільний пролог каналу | Експорти спільного прологу plugin каналу | + | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо group-access | - | `plugin-sdk/direct-dm` | Допоміжні засоби прямого DM | Спільні допоміжні засоби auth/guard для прямого DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status і ambient proxy | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook та встановлення маршрутів | + | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби ухвалення рішень щодо доступу до груп | + | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status та ambient proxy | + | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Реєстр цілей Webhook і допоміжні засоби встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів менеджера пам’яті/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання рушія пам’яті | Фасад середовища виконання індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти базового рушія хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний провайдер і узагальнені допоміжні засоби batch/remote; конкретні віддалені провайдери розміщуються у plugin-ах, яким вони належать | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Експорти рушія сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | Допоміжні засоби multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | Допоміжні засоби query хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста пам’яті | Допоміжні засоби стану хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Середовище виконання CLI хоста пам’яті | Допоміжні засоби середовища виконання CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Основне середовище виконання хоста пам’яті | Основні допоміжні засоби середовища виконання хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім основного середовища виконання хоста пам’яті | Незалежний від постачальника псевдонім для основних допоміжних засобів середовища виконання хоста пам’яті | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Незалежний від постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Незалежний від постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugin-ів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад середовища виконання менеджера пошуку active-memory | - | `plugin-sdk/memory-host-status` | Псевдонім стану хоста пам’яті | Незалежний від постачальника псевдонім для допоміжних засобів стану хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks | + | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів менеджера/config/файлів/CLI для memory | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime engine memory | Фасад runtime індексу/пошуку memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста memory | Експорти foundation engine хоста memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста memory | Контракти embeddings memory, доступ до реєстру, локальний provider і універсальні batch/remote допоміжні засоби; конкретні remote provider розміщуються у plugin, яким вони належать | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста memory | Експорти QMD engine хоста memory | + | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста memory | Експорти storage engine хоста memory | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста memory | Мультимодальні допоміжні засоби хоста memory | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста memory | Допоміжні засоби запитів хоста memory | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста memory | Допоміжні засоби секретів хоста memory | + | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста memory | Допоміжні засоби журналу подій хоста memory | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста memory | Допоміжні засоби статусу хоста memory | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста memory | Допоміжні засоби CLI runtime хоста memory | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста memory | Допоміжні засоби core runtime хоста memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста memory | Допоміжні засоби файлів/runtime хоста memory | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста memory | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста memory | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста memory | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста memory | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста memory | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста memory | + | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugin, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory | + | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста memory | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста memory | + | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні засоби memory-lancedb | Поверхня допоміжних засобів memory-lancedb | + | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби та моки для тестування | -Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною -поверхнею SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною поверхнею SDK. Повний список із понад 200 точок входу міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі шви допоміжних засобів вбудованих plugin-ів, як-от +Цей список усе ще включає деякі шви допоміжних засобів для вбудованих plugin, такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для -підтримки та сумісності вбудованих plugin-ів, але навмисно -не включені до поширеної таблиці міграції й не є рекомендованою ціллю для -нового коду plugin-ів. +`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для +підтримки та сумісності вбудованих plugin, але навмисно +не включені до поширеної таблиці міграції та не є рекомендованою ціллю для +нового коду plugin. -Те саме правило застосовується до інших сімейств допоміжних засобів вбудованих plugin-ів, таких як: +Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як: - допоміжні засоби підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих допоміжних засобів/plugin-ів, як-от `plugin-sdk/googlechat`, +- поверхні вбудованих допоміжних засобів/plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -364,34 +363,34 @@ OpenClaw перейшов від широкого шару зворотної с `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти експорт, -перевірте код у `src/plugin-sdk/` або запитайте в Discord. +перевірте джерело в `src/plugin-sdk/` або запитайте в Discord. -## Графік вилучення +## Часова шкала видалення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | | **Зараз** | Застарілі поверхні генерують попередження під час виконання | -| **Наступний мажорний випуск** | Застарілі поверхні буде вилучено; plugin-и, які досі їх використовують, перестануть працювати | +| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; plugin, які досі їх використовують, перестануть працювати | -Усі основні plugin-и вже мігровано. Зовнішнім plugin-ам слід виконати міграцію +Усі core plugin уже мігровано. Зовнішнім plugin слід виконати міграцію до наступного мажорного випуску. ## Тимчасове приглушення попереджень -Встановіть ці змінні середовища, поки працюєте над міграцією: +Установіть ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий запасний варіант, а не постійне рішення. +Це тимчасовий аварійний обхід, а не постійне рішення. ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту підшляхів -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugin-ів -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugin-ів -- [Внутрішня будова plugin-ів](/uk/plugins/architecture) — глибокий огляд архітектури -- [Маніфест plugin-а](/uk/plugins/manifest) — довідник схеми маніфесту +- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення plugin каналів +- [Плагіни provider](/uk/plugins/sdk-provider-plugins) — створення plugin provider +- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибоке занурення в архітектуру +- [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 06dab8eee..d65198215 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - Вам потрібно знати, з якого підшляху SDK імпортувати. - - Вам потрібен довідник з усіх методів реєстрації в OpenClawPluginApi. - - Ви шукаєте конкретний експорт SDK. + - Вам потрібно знати, з якого підшляху SDK імпортувати + - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview -summary: Мапа імпорту, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-21T20:37:39Z" + generated_at: "2026-04-22T01:34:41Z" model: gpt-5.4 provider: openai - source_hash: 16ef34e4ad4550967d06ea6bd94b3400431c0fb536bf267cc4e8a09ec9483695 + source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673 source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між plugin-ами та ядром. Ця сторінка є -довідником з **того, що імпортувати**, і **того, що можна зареєструвати**. +Plugin SDK — це типізований контракт між plugin і ядром. Ця сторінка — +довідник щодо **що імпортувати** і **що можна реєструвати**. - **Шукаєте покроковий посібник?** + **Шукаєте практичний посібник?** - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) - Channel plugin? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - Provider plugin? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) -## Правило імпорту +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -36,40 +36,40 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і -запобігає проблемам із циклічними залежностями. Для специфічних для channel -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої парасолькової поверхні та спільних допоміжних засобів, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий +запуск і запобігає проблемам із циклічними залежностями. Для специфічних до channel +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` +залишайте для ширшої поверхні-парасольки та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. -Не додавайте і не використовуйте зручні шари з назвами provider-ів, такі як +Не додавайте й не використовуйте зручні шви з назвами provider, такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шари, брендові для channel. Вбудовані plugin-и мають компонувати узагальнені +допоміжні шви з брендуванням channel. Вбудовані plugins мають компонувати загальні підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці локальні для plugin-а barrel-файли, або додавати вузький узагальнений контракт SDK, -коли така потреба справді є між channel-ами. +має або використовувати ці локальні barrel-файли plugin, або додавати вузький загальний SDK +контракт, коли потреба справді є міжchannel-ною. -Згенерована мапа експорту все ще містить невеликий набір допоміжних -шарів для вбудованих plugin-ів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Згенерована карта експорту все ще містить невеликий набір допоміжних +швів для вбудованих plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для підтримки та сумісності вбудованих plugin-ів; вони -навмисно не включені до загальної таблиці нижче й не є рекомендованим -шляхом імпорту для нових сторонніх plugin-ів. +підшляхи існують лише для підтримки вбудованих plugins і сумісності; їх +навмисно не включено до загальної таблиці нижче, і вони не є +рекомендованим шляхом імпорту для нових сторонніх plugins. ## Довідник підшляхів Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із -понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. +понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи для вбудованих plugin-ів усе ще з’являються в цьому згенерованому списку. -Розглядайте їх як поверхні деталей реалізації/сумісності, якщо лише сторінка документації -явно не позначає одну з них як публічну. +Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому +згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності, +якщо лише якась сторінка документації явно не просуває один із них як публічний. -### Entry plugin-а +### Вхід plugin -| Підшлях | Ключові експорти | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Subpath | Key exports | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | @@ -77,216 +77,216 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Кореневий експорт Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, збирачі статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, будівники статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для мультиакаунтної конфігурації/гейтів дій, допоміжні засоби резервного вибору акаунта за замовчуванням | + | `plugin-sdk/account-core` | Допоміжні засоби для багатoакаунтної конфігурації/шлюзів дій, допоміжні засоби резервного переходу до облікового запису за замовчуванням | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку акаунта + резервного вибору за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку акаунтів/дій з акаунтами | + | `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного переходу до типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації channel | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою контракту вбудованих plugin-ів | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби гейту авторизації команд | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою контракту вбудованого plugin | + | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й dispatch для вхідних повідомлень | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернеток | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації inbound і побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й dispatch для inbound | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності, делегата надсилання та планування payload | + | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження outbound media | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound-ідентичності, делегата надсилання та планування payload | | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий builder payload медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки conversation/thread, pairing та налаштованих binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення policy груп у runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary статусу channel | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий будівник agent media payload | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy у runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку статусу channel | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації channel | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації channel | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin-ів | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти plugin channel | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень щодо доступу груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Message Presentation](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів policy згадок і допоміжних засобів envelope | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби policy згадок без ширшої surface runtime вхідних повідомлень | - | `plugin-sdk/channel-location` | Допоміжні засоби контексту розташування channel та форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування channel для відкидання вхідних повідомлень і збоїв typing/ack | - | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями channel, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності plugin-ів | + | `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямого DM | + | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Message Presentation](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Compatibility barrel для debounce inbound, зіставлення згадок, допоміжних засобів mention-policy та допоміжних засобів envelope | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy без ширшої поверхні inbound runtime | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту та форматування розташування channel | + | `plugin-sdk/channel-logging` | Допоміжні засоби логування channel для відкидання inbound і збоїв typing/ack | + | `plugin-sdk/channel-send-result` | Типи результату відповіді | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями channel, а також застарілі нативні допоміжні засоби schema, збережені для сумісності plugin | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контракту channel | + | `plugin-sdk/channel-contract` | Типи контрактів channel | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту secret, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | - | `plugin-sdk/cli-backend` | Значення CLI backend за замовчуванням + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для provider plugin-ів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний builder результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider plugin-ів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env-var auth provider-а | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-key у runtime для provider plugins | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-key, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний будівник OAuth auth-result | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider plugins | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку auth env var для provider | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и policy повторного відтворення, допоміжні засоби endpoint provider-а та допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні будівники replay-policy, допоміжні засоби endpoint provider і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Узагальнені допоміжні засоби HTTP/capability endpoint provider-а | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування provider-а web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider-ів, яким не потрібне підключення enable plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime provider-а web-search | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint для provider | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування provider для web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для provider, яким не потрібне підключення enable plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter облікових даних з обмеженою областю дії | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime provider для web-search | | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби транспорту provider-а, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту із можливістю запису | - | `plugin-sdk/provider-onboard` | Допоміжні засоби patch конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні засоби локального для процесу singleton/map/cache | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби transport для provider, такі як guarded fetch, трансформації transport message і writable потоки transport event | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Builder-и повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver-а та auth дій у тому ж чаті | - | `plugin-sdk/approval-client-runtime` | Нативні допоміжні засоби профілю/фільтра approval для exec | - | `plugin-sdk/approval-delivery-runtime` | Нативні адаптери capability/delivery approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway для approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені нативні допоміжні засоби завантаження адаптера approval для гарячих entrypoint-ів channel | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime handler-а approval; віддавайте перевагу вужчим шарам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби цілі approval + прив’язки акаунта | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді approval для exec/plugin | - | `plugin-sdk/command-auth-native` | Нативний auth команд + нативні допоміжні засоби session-target | + | `plugin-sdk/command-status` | Будівники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і auth дій у межах того самого чату | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval Gateway | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native approval adapter для гарячих entrypoint channel | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби approval handler runtime; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + account-binding | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для exec/plugin approval | + | `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команд | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації command-body і command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-контрактів для поверхонь secret channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу secret-контрактів/конфігурації | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, гейтингу DM, зовнішнього вмісту та збирання secret | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби policy SSRF для allowlist хостів і приватної мережі | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні runtime infra | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і policy SSRF | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору secret-contract для поверхонь secret channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього контенту та збору secret | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | | `plugin-sdk/secret-input` | Допоміжні засоби парсингу secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout запиту | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body/timeout запиту | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/установлення plugin-ів | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення plugin | | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | - | `plugin-sdk/channel-runtime-context` | Узагальнені допоміжні засоби реєстрації та пошуку runtime-context channel | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context channel | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive plugin-а | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy-імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версії | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і patch статусу channel | - | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації імені/опису команд Telegram та перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel-а text-runtime | - | `plugin-sdk/approval-runtime` | Допоміжні засоби approval для exec/plugin, builder-и capability approval, допоміжні засоби auth/profile, нативної маршрутизації/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, planner відповіді | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису config | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, будівники approval capability, допоміжні засоби auth/profile, native routing/runtime helpers | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, чанкування, dispatch, Heartbeat, planner відповіді | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповіді | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби історії відповідей для короткого вікна, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + `updated-at` | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій state/OAuth | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби чанкування text/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до session store + `updated-at` | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | | `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби summary статусу channel/акаунта, значення стану runtime за замовчуванням і допоміжні засоби метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби resolver-а цілей | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу channel/account, типові значення runtime-state і допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби resolver цілей | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із входів, подібних до fetch/request | - | `plugin-sdk/run-command` | Runner команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | + | `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних входів | + | `plugin-sdk/run-command` | Runner команд із таймуванням і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI | | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів для тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби logger-а підсистеми та редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/logging-core` | Допоміжні засоби логера підсистем і редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму Markdown-таблиць | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесії ACP і dispatch відповіді | - | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Зчитувач нестрогих boolean-параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe з дисковим збереженням | + | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і dispatch відповіді | + | `plugin-sdk/acp-binding-resolve-runtime` | Визначення ACP binding лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema config runtime для agent | + | `plugin-sdk/boolean-param` | Нестрогий читач boolean-параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та pairing token | | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команд/provider-ів `/models` | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize нативних команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw і утиліти результатів attempt | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді для команди `/models`/provider | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби лістингу команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native command | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби мосту tool OpenClaw і утиліти результатів attempt | | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/Heartbeat | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy та pinned lookup | - | `plugin-sdk/runtime-fetch` | Fetch runtime з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Зчитувач обмеженого body відповіді без широкої поверхні runtime медіа | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації налаштованих binding або сховищ pairing | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби читання сховища сесій без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів конфігурації/безпеки | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації примітивних record/string без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і runner-а retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація директорій на основі конфігурації | + | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Читач body відповіді з обмеженням без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан binding розмови без configured binding routing або pairing store | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби читання session-store без широких імпортів запису/обслуговування config | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імен хостів і хостів SCP | + | `plugin-sdk/retry-runtime` | Допоміжні засоби config retry і runner retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace для agent | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогів на основі config | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Підшлях | Ключові експорти | + + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа, а також builder-и payload медіа | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибору кандидатів і повідомлень про відсутню модель | - | `plugin-sdk/media-understanding` | Типи provider-а для розуміння медіа, а також provider-орієнтовані експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи provider-а мовлення, а також provider-орієнтовані допоміжні засоби директив, реєстру і валідації | - | `plugin-sdk/speech-core` | Спільні допоміжні засоби типів, реєстру, директив і нормалізації provider-а мовлення | - | `plugin-sdk/realtime-transcription` | Типи provider-а транскрипції в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи provider-а голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи provider-а генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні допоміжні засоби типів, failover, auth і реєстру генерації зображень | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для media, а також будівники media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації media, вибір кандидатів і повідомлення про відсутню model | + | `plugin-sdk/media-understanding` | Типи provider для розуміння media, а також provider-oriented експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення тексту, видимого assistant, допоміжні засоби рендерингу/чанкування/таблиць markdown, редагування чутливих даних, допоміжні засоби тегів directive і утиліти безпечного text | + | `plugin-sdk/text-chunking` | Допоміжний засіб чанкування outbound text | + | `plugin-sdk/speech` | Типи provider для мовлення, а також provider-oriented допоміжні засоби directive, registry і validation | + | `plugin-sdk/speech-core` | Спільні типи provider для мовлення, а також допоміжні засоби registry, directive і normalization | + | `plugin-sdk/realtime-transcription` | Типи provider для транскрипції в реальному часі та допоміжні засоби registry | + | `plugin-sdk/realtime-voice` | Типи provider для голосу в реальному часі та допоміжні засоби registry | + | `plugin-sdk/image-generation` | Типи provider для генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, а також допоміжні засоби failover, auth і registry | | `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики | - | `plugin-sdk/music-generation-core` | Спільні допоміжні засоби типів генерації музики, failover, пошуку provider-а та парсингу model-ref | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, lookup provider і парсинг model-ref | | `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео | - | `plugin-sdk/video-generation-core` | Спільні допоміжні засоби типів генерації відео, failover, пошуку provider-а та парсингу model-ref | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, lookup provider і парсинг model-ref | | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних media | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для менеджера/конфігурації/файлів/допоміжних засобів CLI | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого `memory-core` для manager/config/file/CLI | | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку Memory | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний provider і узагальнені допоміжні засоби batch/remote | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до registry, локальний provider і загальні допоміжні засоби batch/remote | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory | | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста Memory | @@ -294,89 +294,89 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста Memory | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста Memory | | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста Memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста Memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста Memory | | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста Memory | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста Memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби file/runtime хоста Memory | | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста Memory | | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста Memory | - | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста Memory | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugin-ів, суміжних із memory | - | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів file/runtime хоста Memory | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugins, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста Memory | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого `memory-lancedb` | - - | Родина | Поточні підшляхи | Призначене використання | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin-а (`browser-support` залишається barrel-ом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper-ів/runtime вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper-ів/runtime вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper-ів вбудованого IRC | - | Специфічні для channel helper-и | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари сумісності/helper-ів вбудованих channel | - | Специфічні для auth/plugin helper-и | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шари helper-ів вбудованих функцій/plugin-ів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається compatibility barrel) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper вбудованого IRC | + | Допоміжні засоби, специфічні для channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів вбудованих channel | + | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для вбудованих функцій/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` із такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: -### Реєстрація capability +### Реєстрація можливостей -| Метод | Що реєструє | -| ------------------------------------------------ | -------------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend inference CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| Method | What it registers | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | Текстове inference (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець agent | +| `api.registerCliBackend(...)` | Локальний backend inference CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | | `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Provider Web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | -### Tools і команди +### Інструменти й команди -| Метод | Що реєструє | -| ------------------------------ | -------------------------------------------- | -| `api.registerTool(tool, opts?)` | Tool агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | +| Method | What it registers | +| ------------------------------- | --------------------------------------------- | +| `api.registerTool(tool, opts?)` | Інструмент agent (обов’язковий або `{ optional: true }`) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура -| Метод | Що реєструє | -| --------------------------------------------- | -------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook подій | -| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний handler | -| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний corpus для пошуку/читання memory | +| Method | What it registers | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook події | +| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фонова служба | +| `api.registerInteractiveHandler(registration)` | Інтерактивний handler | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання memory | -Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, +Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити -вужчу область видимості методу Gateway. Для методів, що належать plugin-у, -віддавайте перевагу префіксам, специфічним для plugin-а. +вужчу область дії методу Gateway. Для методів, що належать plugin, +віддавайте перевагу префіксам, специфічним для plugin. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, що належать registrar-у +- `commands`: явні корені команд, що належать registrar - `descriptors`: дескриптори команд на етапі парсингу, які використовуються для кореневої довідки CLI, - маршрутизації та lazy-реєстрації CLI plugin-а + маршрутизації та lazy-реєстрації CLI plugin -Якщо ви хочете, щоб команда plugin-а залишалася lazy-loaded у звичайному кореневому шляху CLI, -надайте `descriptors`, що охоплюють кожен корінь команди верхнього рівня, який відкриває -цей registrar. +Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному кореневому шляху CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що відкривається цим +registrar. ```typescript api.registerCli( @@ -388,7 +388,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю", + description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -396,135 +396,134 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, коли вам не потрібна lazy-реєстрація кореневого CLI. -Цей eager-шлях сумісності залишається підтримуваним, але він не встановлює -placeholder-и на основі descriptor для lazy-завантаження на етапі парсингу. +Використовуйте `commands` окремо лише тоді, коли вам не потрібна lazy-реєстрація кореневого CLI. +Цей eager-сумісний шлях і надалі підтримується, але він не встановлює +плейсхолдери на основі descriptor для lazy-loading під час парсингу. -### Реєстрація CLI backend +### Реєстрація backend CLI -`api.registerCliBackend(...)` дає plugin-у змогу володіти конфігурацією за замовчуванням для локального -AI CLI backend, такого як `codex-cli`. +`api.registerCliBackend(...)` дозволяє plugin володіти типовою config для локального +backend CLI AI, такого як `codex-cli`. -- `id` backend-у стає префіксом provider-а в model ref, наприклад `codex-cli/gpt-5`. -- `config` backend-у використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має перевагу. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - значення plugin-а за замовчуванням перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття - (наприклад, для нормалізації старих форм прапорців). +- `id` backend стає префіксом provider у model ref, як-от `codex-cli/gpt-5`. +- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх + типового значення plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після злиття + (наприклад, для нормалізації старих форм flags). ### Ексклюзивні слоти -| Метод | Що реєструє | -| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (лише один активний одночасно). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. | -| `api.registerMemoryCapability(capability)` | Уніфіковану capability memory | -| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt для memory | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory | +| Method | What it registers | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг адаптувати доповнення до prompt. | +| `api.registerMemoryCapability(capability)` | Єдина можливість memory | +| `api.registerMemoryPromptSection(builder)` | Будівник розділу prompt для memory | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory | -### Адаптери embedding для Memory +### Адаптери embedding для memory -| Метод | Що реєструє | -| --------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для Memory для активного plugin-а | +| Method | What it registers | +| ---------------------------------------------- | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin | -- `registerMemoryCapability` — це рекомендований API ексклюзивного plugin-а memory. -- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб companion plugin-и могли споживати експортовані артефакти memory через - `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватного layout - конкретного plugin-а memory. +- `registerMemoryCapability` — це рекомендований API ексклюзивного plugin memory. +- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, + щоб супутні plugins могли споживати експортовані артефакти memory через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного + компонування конкретного plugin memory. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивних plugin-ів memory. -- `registerMemoryEmbeddingProvider` дає активному plugin-у memory змогу зареєструвати один - або більше id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький id, - визначений plugin-ом). + `registerMemoryRuntime` — це застаріло-сумісні API ексклюзивного plugin memory. +- `registerMemoryEmbeddingProvider` дозволяє активному plugin memory реєструвати один + або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький + id, визначений plugin). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, визначається відносно зареєстрованих id цих - адаптерів. + `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих + id адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| ------------------------------------------- | ------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки conversation | +| Method | What it does | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик binding розмови | -### Семантика рішень hook-ів +### Семантика рішень hook - `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. +- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. - `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler заявляє про dispatch, handler-и з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. +- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере на себе dispatch, handler-и з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. - `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як і пропуск `cancel`), а не перевизначенням. +- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення. ### Поля об’єкта API -| Поле | Тип | Опис | +| Field | Type | Description | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID plugin-а | +| `api.id` | `string` | Ідентифікатор plugin | | `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія plugin-а (необов’язково) | -| `api.description` | `string?` | Опис plugin-а (необов’язково) | -| `api.source` | `string` | Шлях до джерела plugin-а | -| `api.rootDir` | `string?` | Коренева директорія plugin-а (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime у пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Специфічна для plugin-а конфігурація з `plugins.entries..config` | +| `api.version` | `string?` | Версія plugin (необов’язково) | +| `api.description` | `string?` | Опис plugin (необов’язково) | +| `api.source` | `string` | Шлях до джерела plugin | +| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок config (активний знімок runtime в пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для plugin, з `plugins.entries..config` | | `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.logger` | `PluginLogger` | Logger з областю дії (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня plugin-а | +| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня plugin | -## Внутрішня угода щодо модулів +## Угода щодо внутрішніх модулів -Усередині вашого plugin-а використовуйте локальні barrel-файли для внутрішніх імпортів: +У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні експорти runtime - index.ts # Точка входу plugin-а - setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) + runtime-api.ts # Експорти runtime лише для внутрішнього використання + index.ts # Точка входу plugin + setup-entry.ts # Полегшене entry лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + у production code. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих plugin-ів, завантажувані через facade (`api.ts`, `runtime-api.ts`, +Публічні поверхні вбудованих plugins, завантажувані через фасад (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають перевагу -активному snapshot конфігурації runtime, коли OpenClaw уже запущений. Якщо snapshot -runtime ще не існує, вони повертаються до визначеного файла конфігурації на диску. +активному знімку config runtime, коли OpenClaw уже працює. Якщо знімок runtime +ще не існує, вони повертаються до визначеного файла config на диску. -Plugin-и provider-ів також можуть надавати вузький локальний barrel контракту plugin-а, коли -допоміжний засіб навмисно є специфічним для provider-а і ще не належить до -узагальненого підшляху SDK. Поточний вбудований приклад: provider Anthropic зберігає свої -допоміжні засоби потоку Claude у власному публічному шарі `api.ts` / `contract-api.ts` замість -просування логіки beta-header Anthropic і `service_tier` до узагальненого -контракту `plugin-sdk/*`. +Plugins provider також можуть відкривати вузький локальний barrel контракту plugin, коли +допоміжний засіб навмисно є специфічним для provider і ще не належить до загального підшляху SDK. +Поточний вбудований приклад: provider Anthropic зберігає свої допоміжні засоби потоку Claude +у власному публічному шві `api.ts` / `contract-api.ts` замість просування логіки +beta-header Anthropic і `service_tier` до загального контракту `plugin-sdk/*`. Інші поточні вбудовані приклади: -- `@openclaw/openai-provider`: `api.ts` експортує builder-и provider-а, - допоміжні засоби моделей за замовчуванням і builder-и provider-а realtime -- `@openclaw/openrouter-provider`: `api.ts` експортує builder provider-а, а також - допоміжні засоби onboarding/config +- `@openclaw/openai-provider`: `api.ts` експортує будівники provider, + допоміжні засоби типових моделей і будівники provider для реального часу +- `@openclaw/openrouter-provider`: `api.ts` експортує будівник provider, а також + допоміжні засоби онбордингу/config - Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді є спільним, просуньте його до нейтрального підшляху SDK, + Production code extension також має уникати імпортів `openclaw/plugin-sdk/`. + Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на capability, замість того щоб зв’язувати два plugin-и між собою. + поверхні, орієнтованої на можливості, замість зв’язування двох plugins між собою. -## Пов’язане +## Пов’язані матеріали - [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` - [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` -- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації +- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми config - [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint - [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — детальна архітектура та модель capability +- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей plugin