diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 597017386..3cf0a7f76 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,107 +1,107 @@ --- read_when: - Робота над функціями каналу Discord -summary: Стан підтримки, можливості та конфігурація бота Discord +summary: Статус підтримки Discord-бота, можливості та конфігурація title: Discord x-i18n: - generated_at: "2026-05-04T00:48:54Z" + generated_at: "2026-05-04T07:02:39Z" model: gpt-5.5 provider: openai - source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 + source_hash: 1e00f9d9b134296ac1ca52bb4058fc62ea7a95c4d46d9478648b2ecdd448652a source_path: channels/discord.md workflow: 16 --- -Готово до особистих повідомлень і каналів серверів через офіційний Discord Gateway. +Готово для DM та каналів гільдій через офіційний Discord gateway. - - Особисті повідомлення Discord за замовчуванням працюють у режимі сполучення. + + Discord DM за замовчуванням переходять у режим сполучення. - + Нативна поведінка команд і каталог команд. - - Міжканальна діагностика та процес відновлення. + + Діагностика між каналами та процес відновлення. ## Швидке налаштування -Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Створити власний > Для мене та моїх друзів**). +Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з OpenClaw. Радимо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). - - Перейдіть до [порталу розробника Discord](https://discord.com/developers/applications) і натисніть **Новий застосунок**. Назвіть його, наприклад, "OpenClaw". + + Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть його, наприклад, "OpenClaw". - Натисніть **Бот** на бічній панелі. Установіть **Ім’я користувача** на те, як ви називаєте свого агента OpenClaw. + Натисніть **Bot** на бічній панелі. Установіть **Username** на назву, якою ви називаєте свого агента OpenClaw. - - Залишаючись на сторінці **Бот**, прокрутіть униз до **Привілейовані наміри Gateway** і увімкніть: + + Залишаючись на сторінці **Bot**, прокрутіть до **Privileged Gateway Intents** і ввімкніть: - - **Намір вмісту повідомлень** (обов’язково) - - **Намір учасників сервера** (рекомендовано; обов’язково для списків дозволених ролей і зіставлення імен з ID) - - **Намір присутності** (необов’язково; потрібен лише для оновлень присутності) + - **Message Content Intent** (обов’язково) + - **Server Members Intent** (рекомендовано; обов’язково для списків дозволених ролей і зіставлення імен з ID) + - **Presence Intent** (необов’язково; потрібен лише для оновлень присутності) - - Прокрутіть назад угору на сторінці **Бот** і натисніть **Скинути токен**. + + Прокрутіть угору на сторінці **Bot** і натисніть **Reset Token**. - Попри назву, це генерує ваш перший токен — нічого не "скидається." + Попри назву, це створює ваш перший токен — нічого не "скидається". - Скопіюйте токен і збережіть його десь. Це ваш **токен бота**, і він знадобиться вам невдовзі. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він незабаром знадобиться. - - Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з правильними дозволами, щоб додати бота на свій сервер. + + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з потрібними дозволами, щоб додати бота на свій сервер. - Прокрутіть униз до **Генератор URL OAuth2** і увімкніть: + Прокрутіть до **OAuth2 URL Generator** і ввімкніть: - `bot` - `applications.commands` - Нижче з’явиться розділ **Дозволи бота**. Увімкніть принаймні: + Нижче з’явиться розділ **Bot Permissions**. Увімкніть щонайменше: - **Загальні дозволи** + **General Permissions** - Перегляд каналів - **Текстові дозволи** + **Text Permissions** - Надсилання повідомлень - Читання історії повідомлень - Вбудовування посилань - Прикріплення файлів - Додавання реакцій (необов’язково) - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в гілках Discord, включно зі сценаріями форумних або медіаканалів, які створюють або продовжують гілку, також увімкніть **Надсилання повідомлень у гілках**. - Скопіюйте згенерований URL внизу, вставте його у браузер, виберіть свій сервер і натисніть **Продовжити**, щоб підключити. Тепер ви маєте бачити свого бота на сервері Discord. + Це базовий набір для звичайних текстових каналів. Якщо плануєте публікувати в тредах Discord, зокрема в робочих процесах форумних або медіаканалів, які створюють чи продовжують тред, також увімкніть **Send Messages in Threads**. + Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue**, щоб під’єднати. Тепер ви маєте бачити свого бота на сервері Discord. - - Повернувшись у застосунок Discord, потрібно увімкнути режим розробника, щоб мати змогу копіювати внутрішні ID. + + Повернувшись у застосунок Discord, потрібно ввімкнути Developer Mode, щоб копіювати внутрішні ID. - 1. Натисніть **Налаштування користувача** (значок шестерні поруч з аватаром) → **Розширені** → увімкніть **Режим розробника** - 2. Клацніть правою кнопкою миші свій **значок сервера** на бічній панелі → **Копіювати ID сервера** - 3. Клацніть правою кнопкою миші свій **власний аватар** → **Копіювати ID користувача** + 1. Натисніть **User Settings** (іконка шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** + 2. Клацніть правою кнопкою миші **іконку сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою миші **свій аватар** → **Copy User ID** - Збережіть свої **ID сервера** та **ID користувача** поруч із токеном бота — на наступному кроці ви надішлете всі три значення в OpenClaw. + Збережіть свої **Server ID** і **User ID** поряд із Bot Token — на наступному кроці ви надішлете всі три до OpenClaw. - - Щоб сполучення працювало, Discord має дозволяти вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою миші свій **значок сервера** → **Налаштування конфіденційності** → увімкніть **Особисті повідомлення**. + + Щоб сполучення працювало, Discord має дозволяти вашому боту надсилати вам DM. Клацніть правою кнопкою миші **іконку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (включно з ботами) надсилати вам особисті повідомлення. Залиште це увімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали сервера, можете вимкнути особисті повідомлення після сполучення. + Це дозволяє учасникам сервера (зокрема ботам) надсилати вам DM. Залиште це ввімкненим, якщо хочете використовувати Discord DM з OpenClaw. Якщо плануєте використовувати лише канали гільдії, можете вимкнути DM після сполучення. - - Токен вашого бота Discord є секретом (як пароль). Задайте його на машині, де запущено OpenClaw, перш ніж писати своєму агенту. + + Токен вашого Discord-бота є секретом (як пароль). Установіть його на машині, де працює OpenClaw, перед тим як писати своєму агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -121,21 +121,21 @@ openclaw gateway ``` Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й повторно запустивши процес `openclaw gateway run`. - Для встановлень як керований сервіс запустіть `openclaw gateway install` з оболонки, де присутній `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб сервіс міг розв’язати env SecretRef після перезапуску. - Якщо ваш хост заблокований або обмежений за частотою запитів під час стартового пошуку застосунку Discord, задайте ID застосунку/клієнта Discord з порталу розробника, щоб запуск міг пропустити цей REST-виклик. Використовуйте `channels.discord.applicationId` для стандартного акаунта або `channels.discord.accounts..applicationId`, коли запускаєте кілька ботів Discord. + Для встановлень керованого сервісу запустіть `openclaw gateway install` з оболонки, де наявний `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб сервіс міг розв’язати env SecretRef після перезапуску. + Якщо ваш хост заблокований або обмежений Discord під час стартового пошуку застосунку, задайте ID застосунку/клієнта Discord з Developer Portal, щоб запуск міг пропустити цей REST-виклик. Використовуйте `channels.discord.applicationId` для стандартного акаунта або `channels.discord.accounts..applicationId`, коли запускаєте кількох ботів Discord. - + - - Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, натомість скористайтеся вкладкою CLI / конфігурація. + + Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому. Якщо Discord — ваш перший канал, використайте вкладку CLI / config натомість. - > "Я вже задав токен свого бота Discord у конфігурації. Будь ласка, заверши налаштування Discord з ID користувача `` та ID сервера ``." + > "I already set my Discord bot token in config. Please finish Discord setup with User ID `` and Server ID ``." - - Якщо віддаєте перевагу файловій конфігурації, задайте: + + Якщо надаєте перевагу файловій конфігурації, задайте: ```json5 { @@ -152,15 +152,15 @@ openclaw gateway } ``` - Резервне значення змінної середовища для стандартного акаунта: + Env fallback для стандартного акаунта: ```bash DISCORD_BOT_TOKEN=... ``` - Для скриптового або віддаленого налаштування запишіть той самий блок JSON5 за допомогою `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім запустіть повторно без `--dry-run`. Підтримуються значення `token` у відкритому тексті. Також підтримуються значення SecretRef для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Для скриптового або віддаленого налаштування запишіть той самий блок JSON5 через `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім повторіть запуск без `--dry-run`. Значення `token` у відкритому тексті підтримуються. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). - Для кількох ботів Discord тримайте токен кожного бота та ID застосунку в його акаунті. Верхньорівневий `channels.discord.applicationId` успадковується акаунтами, тож задавайте його там лише тоді, коли кожен акаунт має використовувати той самий ID застосунку. + Для кількох ботів Discord тримайте токен кожного бота та ID застосунку в його акаунті. Верхньорівневий `channels.discord.applicationId` успадковується акаунтами, тому встановлюйте його там лише тоді, коли кожен акаунт має використовувати той самий ID застосунку. ```json5 { @@ -187,14 +187,14 @@ DISCORD_BOT_TOKEN=... - - Дочекайтеся, доки Gateway запуститься, потім надішліть особисте повідомлення своєму боту в Discord. Він відповість кодом сполучення. + + Дочекайтеся, доки gateway запуститься, а потім напишіть своєму боту в DM у Discord. Він відповість кодом сполучення. - + Надішліть код сполучення своєму агенту в наявному каналі: - > "Схвали цей код сполучення Discord: ``" + > "Approve this Discord pairing code: ``" @@ -208,30 +208,30 @@ openclaw pairing approve discord Коди сполучення спливають через 1 годину. - Тепер ви маєте мати змогу спілкуватися зі своїм агентом у Discord через особисті повідомлення. + Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через DM. -Розв’язання токена враховує акаунт. Значення токена в конфігурації мають пріоритет над резервним значенням env. `DISCORD_BOT_TOKEN` використовується лише для стандартного акаунта. -Якщо два ввімкнені акаунти Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один монітор Gateway для цього токена. Токен із конфігурації має пріоритет над стандартним резервним значенням env; інакше перемагає перший увімкнений акаунт, а дубльований акаунт повідомляється як вимкнений. -Для розширених вихідних викликів (інструмент повідомлень/дії каналів) явний `token` для окремого виклику використовується саме для цього виклику. Це стосується дій надсилання та дій типу читання/перевірки (наприклад read/search/fetch/thread/pins/permissions). Налаштування політики акаунта/повторних спроб усе одно беруться з вибраного акаунта в активному знімку runtime. +Розв’язання токенів враховує акаунт. Значення токена з конфігурації мають пріоритет над env fallback. `DISCORD_BOT_TOKEN` використовується лише для стандартного акаунта. +Якщо два ввімкнені акаунти Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один монітор gateway для цього токена. Токен із конфігурації має пріоритет над стандартним env fallback; інакше перемагає перший увімкнений акаунт, а дубльований акаунт повідомляється як вимкнений. +Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується саме для цього виклику. Це застосовується до дій надсилання та читання/перевірки (наприклад read/search/fetch/thread/pins/permissions). Політики акаунта й налаштування повторних спроб усе одно беруться з вибраного акаунта в активному runtime snapshot. -## Рекомендовано: налаштуйте серверний робочий простір +## Рекомендовано: налаштуйте робочий простір гільдії -Коли особисті повідомлення запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента зі своїм контекстом. Це рекомендовано для приватних серверів, де є лише ви і ваш бот. +Коли DM запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента зі своїм контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. - - Це дає змогу вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в особистих повідомленнях. + + Це дає змогу вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в DM. - - > "Додай ID мого сервера Discord `` до списку дозволених серверів" + + > "Add my Discord Server ID `` to the guild allowlist" - + ```json5 { @@ -254,19 +254,19 @@ openclaw pairing approve discord - - За замовчуванням ваш агент відповідає в каналах сервера лише коли його згадано через @. Для приватного сервера ви, ймовірно, хочете, щоб він відповідав на кожне повідомлення. + + За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його згадують через @mention. Для приватного сервера ви, ймовірно, хочете, щоб він відповідав на кожне повідомлення. - У серверних каналах звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно надсилати явно за допомогою інструмента `message`, щоб агент міг за замовчуванням мовчки спостерігати й публікувати тільки тоді, коли вирішить, що відповідь у каналі корисна. + У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід у Discord треба надсилати явно інструментом `message`, щоб агент міг за замовчуванням перебувати в режимі спостереження й публікувати тільки тоді, коли вирішить, що відповідь у каналі корисна. - Це означає, що вибрана модель має надійно викликати інструменти. Якщо Discord показує індикатор набору, а в логах є використання токенів, але повідомлення не опубліковано, перевірте журнал сесії на текст асистента з `didSendViaMessagingTool: false`. Це означає, що модель створила приватну фінальну відповідь замість виклику `message(action=send)`. Перейдіть на сильнішу модель для виклику інструментів або скористайтеся конфігурацією нижче, щоб відновити застарілі автоматичні фінальні відповіді. + Це означає, що вибрана модель має надійно викликати інструменти. Якщо Discord показує індикатор набору, а журнали показують використання токенів, але повідомлення не публікується, перевірте журнал сесії на наявність тексту асистента з `didSendViaMessagingTool: false`. Це означає, що модель створила приватну фінальну відповідь замість виклику `message(action=send)`. Перейдіть на сильнішу модель для виклику інструментів або використайте конфігурацію нижче, щоб відновити застарілі автоматичні фінальні відповіді. - - > "Дозволь моєму агенту відповідати на цьому сервері без потреби згадувати його через @" + + > "Allow my agent to respond on this server without having to be @mentioned" - - Задайте `requireMention: false` у конфігурації вашого сервера: + + Установіть `requireMention: false` у конфігурації гільдії: ```json5 { @@ -282,61 +282,61 @@ openclaw pairing approve discord } ``` - Щоб відновити застарілі автоматичні фінальні відповіді для групових/канальних кімнат, задайте `messages.groupChat.visibleReplies: "automatic"`. + Щоб відновити застарілі автоматичні фінальні відповіді для групових/канальних кімнат, установіть `messages.groupChat.visibleReplies: "automatic"`. - - За замовчуванням довготривала пам’ять (MEMORY.md) завантажується лише в сесіях особистих повідомлень. Канали сервера не завантажують MEMORY.md автоматично. + + За замовчуванням довготривала пам’ять (MEMORY.md) завантажується лише в DM-сесіях. Канали гільдії не завантажують MEMORY.md автоматично. - - > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довготривалий контекст з MEMORY.md." + + > "When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md." - - Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони вставляються в кожну сесію). Тримайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них на вимогу за допомогою інструментів пам’яті. + + Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони ін’єктуються для кожної сесії). Зберігайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби через інструменти пам’яті. -Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкуватися. Ваш агент бачить назву каналу, а кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що відповідає вашому робочому процесу. +Тепер створіть кілька каналів на своєму сервері Discord і почніть спілкуватися. Ваш агент бачить назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що відповідає вашому робочому процесу. -## Модель виконання +## Модель runtime -- Gateway відповідає за з’єднання Discord. -- Маршрутизація відповідей детермінована: вхідні відповіді з Discord повертаються в Discord. -- Метадані гільдії/каналу Discord додаються до підказки моделі як ненадійний +- Gateway керує з'єднанням Discord. +- Маршрутизація відповідей є детермінованою: вхідні відповіді Discord повертаються до Discord. +- Метадані гільдії/каналу Discord додаються до підказки моделі як недовірений контекст, а не як видимий користувачу префікс відповіді. Якщо модель копіює цей конверт назад, OpenClaw вилучає скопійовані метадані з вихідних відповідей і з майбутнього контексту повторного відтворення. - За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують головну сесію агента (`agent:main:main`). -- Канали гільдій є ізольованими ключами сесій (`agent::discord:channel:`). -- Групові DM ігноруються за замовчуванням (`channels.discord.dm.groupEnabled=false`). -- Нативні slash-команди виконуються в ізольованих командних сесіях (`agent::discord:slash:`), але все одно передають `CommandTargetSessionKey` до маршрутизованої сесії розмови. -- Доставка текстових оголошень Cron/Heartbeat у Discord використовує фінальну - видиму асистенту відповідь один раз. Медіа та структуровані payload-и компонентів залишаються - багатоповідомленнєвими, коли агент випускає кілька доставлюваних payload-ів. +- Канали гільдій мають ізольовані ключі сесій (`agent::discord:channel:`). +- Групові DM за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). +- Нативні slash-команди виконуються в ізольованих командних сесіях (`agent::discord:slash:`), водночас несучи `CommandTargetSessionKey` до маршрутизованої сесії розмови. +- Доставка текстових оголошень Cron/Heartbeat до Discord використовує остаточну + видиму асистенту відповідь один раз. Медіа та структуровані payload компонентів залишаються + багатоповідомленнєвими, коли агент видає кілька доставних payload. ## Канали форумів -Форумні та медіаканали Discord приймають лише дописи в тредах. OpenClaw підтримує два способи їх створення: +Канали форумів і медіаканали Discord приймають лише дописи в тредах. OpenClaw підтримує два способи їх створення: -- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити тред. Назва треду використовує перший непорожній рядок вашого повідомлення. -- Використайте `openclaw message thread create`, щоб створити тред напряму. Не передавайте `--message-id` для форумних каналів. +- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити тред. Назвою треду буде перший непорожній рядок вашого повідомлення. +- Використайте `openclaw message thread create`, щоб створити тред напряму. Не передавайте `--message-id` для каналів форумів. -Приклад: надіслати до батьківського форуму, щоб створити тред +Приклад: надсилання до батьківського форуму для створення треду ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Приклад: явно створити форумний тред +Приклад: явне створення треду форуму ```bash openclaw message thread create --channel discord --target channel: \ @@ -347,7 +347,7 @@ openclaw message thread create --channel discord --target channel: \ ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload-ом `components`. Результати взаємодій маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: @@ -355,13 +355,13 @@ OpenClaw підтримує контейнери компонентів Discord - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, виборів і форм до завершення строку їхньої дії. +За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити використовувати кнопки, вибори та форми кілька разів, доки вони не завершать термін дії. -Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі без збігу отримують ефемерну відмову. +Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, невідповідні користувачі отримують ефемерну відмову. -Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору ефемерна, і користуватися нею може лише користувач, який її викликав. +Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору є ефемерною, і використовувати її може лише користувач, який її викликав. -Файлові вкладення: +Вкладення файлів: - Блоки `file` мають указувати на посилання вкладення (`attachment://`) - Надайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів @@ -369,7 +369,7 @@ Slash-команди `/model` і `/models` відкривають інтерак Модальні форми: -- Додайте `components.modal` із до 5 полями +- Додайте `components.modal` з до 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -431,37 +431,37 @@ Slash-команди `/model` і `/models` відкривають інтерак - `channels.discord.dmPolicy` керує доступом до DM. `channels.discord.allowFrom` є канонічним списком дозволених DM. + `channels.discord.dmPolicy` керує доступом DM. `channels.discord.allowFrom` є канонічним списком дозволених DM. - `pairing` (за замовчуванням) - `allowlist` - - `open` (вимагає, щоб `channels.discord.allowFrom` містив `"*"`) + - `open` (потребує, щоб `channels.discord.allowFrom` містив `"*"`) - `disabled` Якщо політика DM не є відкритою, невідомі користувачі блокуються (або отримують запит на pairing у режимі `pairing`). - Пріоритетність кількох облікових записів: + Пріоритет для кількох облікових записів: - `channels.discord.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - Для одного облікового запису `allowFrom` має пріоритет над застарілим `dm.allowFrom`. - - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не встановлені. + - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не задані. - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. - Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` усе ще читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли може зробити це без зміни доступу. + Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. Формат цілі DM для доставки: - `user:` - згадка `<@id>` - Голі числові ID зазвичай розпізнаються як ID каналів, коли активне значення каналу за замовчуванням, але ID, перелічені в ефективному DM `allowFrom` облікового запису, трактуються як цілі користувацьких DM для сумісності. + Голі числові ID зазвичай розпізнаються як ID каналів, коли активне значення каналу за замовчуванням, але ID, перелічені в ефективному DM `allowFrom` облікового запису, трактуються як цілі DM користувача для сумісності. DM Discord можуть використовувати динамічні записи `accessGroup:` у `channels.discord.allowFrom`. - Назви груп доступу спільні для каналів повідомлень. Використовуйте `type: "message.senders"` для статичної групи, учасники якої виражені у звичайному синтаксисі `allowFrom` кожного каналу, або `type: "discord.channelAudience"`, коли поточна аудиторія `ViewChannel` каналу Discord має динамічно визначати членство. Спільна поведінка груп доступу задокументована тут: [Групи доступу](/uk/channels/access-groups). + Назви груп доступу спільні для каналів повідомлень. Використовуйте `type: "message.senders"` для статичної групи, учасники якої виражені у звичайному синтаксисі `allowFrom` кожного каналу, або `type: "discord.channelAudience"`, коли поточна аудиторія `ViewChannel` каналу Discord має визначати членство динамічно. Поведінка спільних груп доступу задокументована тут: [Групи доступу](/uk/channels/access-groups). ```json5 { @@ -507,7 +507,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Ви можете змішувати динамічні та статичні записи: + Можна змішувати динамічні та статичні записи: ```json5 { @@ -527,29 +527,29 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Пошуки завершуються закритою відмовою. Якщо Discord повертає `Missing Access`, пошук учасника не вдається або канал належить іншій гільдії, відправник DM вважається неавторизованим. + Пошуки відмовляють за замовчуванням. Якщо Discord повертає `Missing Access`, пошук учасника зазнає невдачі або канал належить іншій гільдії, відправник DM вважається неавторизованим. - Увімкніть **Server Members Intent** для бота в Discord Developer Portal під час використання груп доступу на основі аудиторії каналу. DM не містять стану учасника гільдії, тому OpenClaw розпізнає учасника через Discord REST під час авторизації. + Увімкніть **Server Members Intent** у Discord Developer Portal для бота, коли використовуєте групи доступу на основі аудиторії каналу. DM не містять стан учасника гільдії, тому OpenClaw розпізнає учасника через Discord REST під час авторизації. - Обробка гільдій керується `channels.discord.groupPolicy`: + Обробкою гільдій керує `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Безпечний базовий рівень, коли існує `channels.discord`, — це `allowlist`. + Безпечний базовий рівень, коли існує `channels.discord`, це `allowlist`. Поведінка `allowlist`: - - гільдія має відповідати `channels.discord.guilds` (бажано `id`, slug приймається) - - необов’язкові списки дозволених відправників: `users` (рекомендовані стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволені, коли збігаються з `users` АБО `roles` - - прямий збіг за іменем/тегом вимкнений за замовчуванням; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як режим сумісності на крайній випадок + - гільдія має збігатися з `channels.discord.guilds` (рекомендовано `id`, slug приймається) + - необов'язкові списки дозволених відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволені, коли вони збігаються з `users` АБО `roles` + - пряме зіставлення імен/тегів за замовчуванням вимкнене; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як режим сумісності на випадок аварії - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів - - якщо гільдія має налаштовані `channels`, канали не зі списку забороняються - - якщо гільдія не має блока `channels`, усі канали в цій дозволеній гільдії дозволені + - якщо для гільдії налаштовано `channels`, канали поза списком заборонені + - якщо гільдія не має блоку `channels`, дозволені всі канали в цій гільдії зі списку дозволених Приклад: @@ -575,35 +575,35 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Якщо ви встановлюєте лише `DISCORD_BOT_TOKEN` і не створюєте блок `channels.discord`, runtime fallback — це `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. + Якщо ви встановили лише `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, runtime fallback буде `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` дорівнює `open`. - Повідомлення гільдій за замовчуванням обмежені згадкою. + Повідомлення гільдій за замовчуванням пропускаються лише за наявності згадки. - Виявлення згадок включає: + Виявлення згадок охоплює: - явну згадку бота - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - неявну поведінку відповіді боту в підтримуваних випадках - Під час написання вихідних повідомлень Discord використовуйте канонічний синтаксис згадок: `<@USER_ID>` для користувачів, `<#CHANNEL_ID>` для каналів і `<@&ROLE_ID>` для ролей. Не використовуйте застарілу форму згадки нікнейма `<@!USER_ID>`. + Під час написання вихідних повідомлень Discord використовуйте канонічний синтаксис згадок: `<@USER_ID>` для користувачів, `<#CHANNEL_ID>` для каналів і `<@&ROLE_ID>` для ролей. Не використовуйте застарілу форму згадки ніка `<@!USER_ID>`. `requireMention` налаштовується для кожної гільдії/каналу (`channels.discord.guilds...`). - `ignoreOtherMentions` необов’язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). + `ignoreOtherMentions` необов'язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). Групові DM: - за замовчуванням: ігноруються (`dm.groupEnabled=false`) - - необов’язковий список дозволених через `dm.groupChannels` (ID каналів або slugs) + - необов'язковий список дозволених через `dm.groupChannels` (ID каналів або slug) -### Маршрутизація агента на основі ролей +### Маршрутизація агентів на основі ролей -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише до гільдії. Якщо прив’язка також установлює інші поля збігу (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив'язки на основі ролей приймають лише ID ролей і оцінюються після прив'язок peer або parent-peer та перед прив'язками лише для гільдії. Якщо прив'язка також задає інші поля зіставлення (наприклад `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -629,49 +629,49 @@ Slash-команди `/model` і `/models` відкривають інтерак ## Нативні команди та авторизація команд -- `commands.native` за замовчуванням має значення `"auto"` і ввімкнено для Discord. +- `commands.native` за замовчуванням має значення `"auto"` й увімкнено для Discord. - Перевизначення для окремого каналу: `channels.discord.commands.native`. -- `commands.native=false` пропускає реєстрацію та очищення slash-команд Discord під час запуску. Раніше зареєстровані команди можуть залишатися видимими в Discord, доки ви не видалите їх із застосунку Discord. -- Авторизація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимими в UI Discord для користувачів без авторизації; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". +- `commands.native=false` пропускає реєстрацію й очищення slash-команд Discord під час запуску. Раніше зареєстровані команди можуть залишатися видимими в Discord, доки ви не видалите їх із застосунку Discord. +- Автентифікація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимими в UI Discord для користувачів без авторизації; виконання все одно застосовує автентифікацію OpenClaw і повертає "not authorized". -Див. [Slash commands](/uk/tools/slash-commands), щоб переглянути каталог команд і поведінку. +Див. [Slash-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. -Стандартні налаштування slash-команд: +Типові налаштування slash-команд: - `ephemeral: true` -## Деталі функції +## Деталі функцій - - Discord підтримує теги відповідей у виводі агента: + + Discord підтримує теги відповіді у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` Керується через `channels.discord.replyToMode`: - - `off` (за замовчуванням) + - `off` (типово) - `first` - `all` - `batched` - Примітка: `off` вимикає неявне створення ланцюжків відповідей. Явні теги `[[reply_to_*]]` все одно враховуються. - `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord за хід. - `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли - вхідний хід був дебаунс-пакетом із кількох повідомлень. Це корисно, - коли вам потрібні нативні відповіді переважно для неоднозначних швидких чатів, а не для кожного + Примітка: `off` вимикає неявне створення ланцюжків відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + `first` завжди додає неявне нативне посилання відповіді до першого вихідного повідомлення Discord для цього ходу. + `batched` додає неявне нативне посилання відповіді Discord лише тоді, коли + вхідний хід був debounced-пакетом із кількох повідомлень. Це корисно, + коли нативні відповіді потрібні переважно для неоднозначних активних чатів, а не для кожного ходу з одним повідомленням. - ID повідомлень передаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень надаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. - - OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` зберігає одну редаговану чернетку статусу та оновлює її прогресом інструментів до фінальної доставки; `streamMode` є застарілим псевдонімом і мігрується автоматично. + + OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення й редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (типово) | `partial` | `block` | `progress`. `progress` зберігає одну редаговану чернетку статусу й оновлює її прогресом інструментів до фінальної доставки; `streamMode` є застарілим alias і мігрується автоматично. - За замовчуванням лишається `off`, оскільки редагування попереднього перегляду Discord швидко впираються в ліміти частоти, коли кілька ботів або Gateway спільно використовують один обліковий запис. + Типове значення лишається `off`, бо редагування попереднього перегляду Discord швидко впираються в rate limit, коли кілька ботів або gateways використовують один обліковий запис. ```json5 { @@ -689,19 +689,38 @@ Slash-команди `/model` і `/models` відкривають інтерак ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` виводить фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). - - Медіа, помилки та фінальні відповіді з явним reply скасовують очікувані редагування попереднього перегляду. - - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. + - `block` випускає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). + - Медіа, помилки й фінальні повідомлення з явною відповіддю скасовують очікувані редагування попереднього перегляду. + - `streaming.preview.toolProgress` (типово `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. + - `streaming.preview.commandText` / `streaming.progress.commandText` керує деталями command/exec у компактних рядках прогресу: `raw` (типово) або `status` (лише мітка інструмента). - Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли потокове передавання `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Приховати сирий текст command/exec, зберігаючи компактні рядки прогресу: + + ```json + { + "channels": { + "discord": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + Трансляція попереднього перегляду підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли трансляцію `block` явно увімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної трансляції. - - Контекст історії гільдії: + + Контекст історії guild: - - `channels.discord.historyLimit` за замовчуванням `20` - - резервне значення: `messages.groupChat.historyLimit` + - типово `channels.discord.historyLimit` — `20` + - fallback: `messages.groupChat.historyLimit` - `0` вимикає Керування історією DM: @@ -709,28 +728,28 @@ Slash-команди `/model` і `/models` відкривають інтерак - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Поведінка потоків: + Поведінка ланцюжків: - - Потоки Discord маршрутизуються як канальні сесії та успадковують конфігурацію батьківського каналу, якщо її не перевизначено. - - Сесії потоків успадковують вибір `/model` рівня сесії батьківського каналу як резерв лише для моделі; локальні для потоку вибори `/model` усе одно мають пріоритет, а історія транскрипту батьківського каналу не копіюється, якщо успадкування транскрипту не ввімкнено. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових авто-потоків ініціалізацію з батьківського транскрипту. Перевизначення для окремих облікових записів розміщені в `channels.discord.accounts..thread.inheritParent`. - - Реакції інструмента повідомлень можуть розв’язувати цілі DM `user:`. - - `guilds..channels..requireMention: false` зберігається під час резервної активації на етапі відповіді. + - Ланцюжки Discord маршрутизуються як сесії каналу й успадковують конфігурацію батьківського каналу, якщо її не перевизначено. + - Сесії ланцюжків успадковують вибір `/model` рівня сесії батьківського каналу як fallback лише для моделі; локальні для ланцюжка вибори `/model` усе одно мають пріоритет, а історія transcript батька не копіюється, якщо не ввімкнено успадкування transcript. + - `channels.discord.thread.inheritParent` (типово `false`) вмикає для нових auto-threads початкове заповнення з батьківського transcript. Перевизначення для окремого облікового запису розміщуються в `channels.discord.accounts..thread.inheritParent`. + - Реакції message-tool можуть розв’язувати цілі DM `user:`. + - `guilds..channels..requireMention: false` зберігається під час fallback активації на етапі відповіді. - Теми каналів додаються як **ненадійний** контекст. Allowlists обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. + Теми каналів вставляються як **ненадійний** контекст. Allowlists обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. - - Discord може прив’язати потік до цілі сесії, щоб подальші повідомлення в цьому потоці продовжували маршрутизуватися до тієї самої сесії (включно із сесіями subagent). + + Discord може прив’язати ланцюжок до цільової сесії, щоб подальші повідомлення в цьому ланцюжку маршрутизувалися до тієї самої сесії (включно із сесіями субагентів). Команди: - - `/focus ` прив’язати поточний/новий потік до цілі subagent/сесії - - `/unfocus` видалити прив’язку поточного потоку + - `/focus ` прив’язати поточний/новий ланцюжок до цілі субагента/сесії + - `/unfocus` видалити прив’язку поточного ланцюжка - `/agents` показати активні запуски та стан прив’язки - - `/session idle ` переглянути/оновити автоматичне скасування фокуса через неактивність для фокусованих прив’язок - - `/session max-age ` переглянути/оновити жорсткий максимальний вік для фокусованих прив’язок + - `/session idle ` переглянути/оновити автоматичне зняття фокуса через неактивність для сфокусованих прив’язок + - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок Конфігурація: @@ -759,23 +778,23 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - `session.threadBindings.*` задає глобальні стандартні значення. + - `session.threadBindings.*` задає глобальні типові значення. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - - `spawnSessions` керує автоматичним створенням/прив’язкою потоків для `sessions_spawn({ thread: true })` і створень потоків ACP. За замовчуванням: `true`. - - `defaultSpawnContext` керує нативним контекстом subagent для прив’язаних до потоку створень. За замовчуванням: `"fork"`. - - Застарілі ключі `spawnSubagentSessions`/`spawnAcpSessions` мігруються командою `openclaw doctor --fix`. - - Якщо прив’язки потоків вимкнені для облікового запису, `/focus` і пов’язані операції прив’язки потоків недоступні. + - `spawnSessions` керує автоматичним створенням/прив’язкою ланцюжків для `sessions_spawn({ thread: true })` і породжень ланцюжків ACP. Типово: `true`. + - `defaultSpawnContext` керує нативним контекстом субагента для породжень, прив’язаних до ланцюжка. Типово: `"fork"`. + - Застарілі ключі `spawnSubagentSessions`/`spawnAcpSessions` мігруються через `openclaw doctor --fix`. + - Якщо прив’язки ланцюжків вимкнено для облікового запису, `/focus` і пов’язані операції прив’язки ланцюжків недоступні. - Див. [Sub-agents](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Configuration Reference](/uk/gateway/configuration-reference). + Див. [Субагенти](/uk/tools/subagents), [Агенти ACP](/uk/tools/acp-agents) і [Довідник конфігурації](/uk/gateway/configuration-reference). - Для стабільних робочих просторів ACP у режимі "always-on" налаштуйте типізовані прив’язки ACP верхнього рівня, націлені на розмови Discord. + Для стабільних "always-on" робочих просторів ACP налаштуйте типізовані прив’язки ACP верхнього рівня, націлені на розмови Discord. Шлях конфігурації: - - `bindings[]` із `type: "acp"` і `match.channel: "discord"` + - `bindings[]` з `type: "acp"` і `match.channel: "discord"` Приклад: @@ -827,19 +846,19 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або потік на місці та зберігає майбутні повідомлення в тій самій сесії ACP. Повідомлення потоку успадковують прив’язку батьківського каналу. - - У прив’язаному каналі або потоці `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки потоків можуть перевизначати розв’язання цілі, поки активні. - - `spawnSessions` обмежує створення/прив’язку дочірніх потоків через `--thread auto|here`. + - `/acp spawn codex --bind here` прив’язує поточний канал або ланцюжок на місці й утримує майбутні повідомлення в тій самій сесії ACP. Повідомлення ланцюжка успадковують прив’язку батьківського каналу. + - У прив’язаному каналі або ланцюжку `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки ланцюжків можуть перевизначати розв’язання цілі, поки активні. + - `spawnSessions` обмежує створення/прив’язку дочірніх ланцюжків через `--thread auto|here`. - Див. [ACP Agents](/uk/tools/acp-agents), щоб дізнатися деталі поведінки прив’язок. + Див. [Агенти ACP](/uk/tools/acp-agents) для деталей поведінки прив’язок. - Режим сповіщень про реакції для окремої гільдії: + Режим сповіщень про реакції для окремого guild: - `off` - - `own` (за замовчуванням) + - `own` (типово) - `all` - `allowlist` (використовує `guilds..users`) @@ -848,28 +867,28 @@ Slash-команди `/model` і `/models` відкривають інтерак - `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. + `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок розв’язання: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - fallback emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Discord приймає unicode-емодзі або назви користувацьких емодзі. + - Discord приймає unicode emoji або назви користувацьких emoji. - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Ініційовані каналом записи конфігурації ввімкнені за замовчуванням. + Записи конфігурації, ініційовані каналом, увімкнено за замовчуванням. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). + Це впливає на потоки `/config set|unset` (коли командні функції ввімкнено). - Вимкнення: + Вимкнути: ```json5 { @@ -884,7 +903,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - Маршрутизуйте WebSocket-трафік Gateway Discord і стартові REST-пошуки (ID застосунку + розв’язання allowlist) через HTTP(S)-проксі з `channels.discord.proxy`. + Маршрутизуйте WebSocket-трафік Gateway Discord і стартові REST-пошуки (application ID + розв’язання allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. ```json5 { @@ -915,7 +934,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - Увімкніть розв’язання PluralKit, щоб зіставляти проксійовані повідомлення з ідентичністю учасника системи: + Увімкніть розв’язання PluralKit, щоб зіставляти проксовані повідомлення з ідентичністю учасника системи: ```json5 { @@ -933,14 +952,14 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - allowlists можуть використовувати `pk:` - - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошуки використовують ID початкового повідомлення та обмежені часовим вікном - - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота та відкидаються, якщо `allowBots=true` не задано + - відображувані імена учасників зіставляються за name/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` + - пошуки використовують ID початкового повідомлення й обмежені часовим вікном + - якщо пошук не вдається, проксовані повідомлення вважаються повідомленнями бота й відкидаються, якщо не встановлено `allowBots=true` - - Використовуйте `mentionAliases`, коли агентам потрібні детерміновані вихідні згадки для відомих користувачів Discord. Ключі — це handle без початкового `@`; значення — ID користувачів Discord. Невідомі handle, `@everyone`, `@here` і згадки всередині Markdown code spans лишаються без змін. + + Використовуйте `mentionAliases`, коли агентам потрібні детерміновані вихідні згадки для відомих користувачів Discord. Ключі — це handles без початкового `@`; значення — ID користувачів Discord. Невідомі handles, `@everyone`, `@here` і згадки всередині Markdown code spans залишаються без змін. ```json5 { @@ -978,7 +997,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Приклад активності (користувацький статус є стандартним типом активності): + Приклад активності (користувацький статус є типовим типом активності): ```json5 { @@ -991,7 +1010,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Приклад потокового передавання: + Приклад streaming: ```json5 { @@ -1008,10 +1027,10 @@ Slash-команди `/model` і `/models` відкривають інтерак Мапа типів активності: - 0: Грає - - 1: Стримить (потребує `activityUrl`) + - 1: Streaming (потребує `activityUrl`) - 2: Слухає - 3: Дивиться - - 4: Користувацька (використовує текст активності як стан статусу; емодзі необов’язковий) + - 4: Custom (використовує текст активності як стан статусу; emoji необов’язковий) - 5: Змагається Приклад автоматичної присутності (сигнал стану runtime): @@ -1031,50 +1050,50 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Автоматична присутність зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: + Автоматична присутність зіставляє доступність runtime зі статусом Discord: справний => онлайн, погіршений або невідомий => бездіяльний, вичерпаний або недоступний => не турбувати. Необов’язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (підтримує placeholder `{reason}`) + - `autoPresence.exhaustedText` (підтримує заповнювач `{reason}`) - Discord підтримує обробку схвалень на основі кнопок у DM і може необов’язково публікувати запити схвалення у вихідному каналі. + Discord підтримує обробку схвалень за допомогою кнопок у DM і може необов’язково публікувати запити на схвалення у вихідному каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості повертається до `commands.ownerAllowFrom`) - - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, стандартно: `dm`) + - `channels.discord.execApprovals.approvers` (необов’язково; коли можливо, використовує запасний варіант `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні підтвердження виконання, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного підтверджувача: з `execApprovals.approvers` або з `commands.ownerAllowFrom`. Discord не виводить підтверджувачів виконання з канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт підтверджень. + Discord автоматично вмикає нативні схвалення виконання, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного схвалювача: або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить схвалювачів виконання з канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Задайте `enabled: false`, щоб явно вимкнути Discord як нативний клієнт схвалень. - Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на підтвердження та фінальні результати приватно. Спочатку він пробує Discord DM, коли власник, який викликав команду, має маршрут власника Discord; якщо він недоступний, OpenClaw повертається до першого доступного маршруту власника з `commands.ownerAllowFrom`, наприклад Telegram. + Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на схвалення та фінальні результати приватно. Спершу він пробує Discord DM, коли власник, який викликає команду, має маршрут власника Discord; якщо він недоступний, використовується перший доступний маршрут власника з `commands.ownerAllowFrom`, наприклад Telegram. - Коли `target` має значення `channel` або `both`, запит на підтвердження видно в каналі. Кнопками можуть користуватися лише визначені підтверджувачі; інші користувачі отримують тимчасову відмову. Запити на підтвердження містять текст команди, тому вмикайте доставлення в канал лише в довірених каналах. Якщо ідентифікатор каналу неможливо отримати з ключа сесії, OpenClaw повертається до доставлення через DM. + Коли `target` має значення `channel` або `both`, запит на схвалення видно в каналі. Користуватися кнопками можуть лише визначені схвалювачі; інші користувачі отримують ефемерну відмову. Запити на схвалення містять текст команди, тому вмикайте доставлення в канал лише в довірених каналах. Якщо ID каналу неможливо отримати з ключа сесії, OpenClaw використовує запасне доставлення через DM. - Discord також рендерить спільні кнопки підтвердження, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для підтверджувачів і розсилання в канали. - Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw - має включати ручну команду `/approve` лише тоді, коли результат інструмента повідомляє, - що підтвердження в чаті недоступні або ручне підтвердження є єдиним шляхом. - Якщо нативне середовище виконання підтверджень Discord не активне, OpenClaw залишає - видимою локальну детерміновану підказку `/approve `. Якщо - середовище виконання активне, але нативну картку неможливо доставити жодній цілі, - OpenClaw надсилає резервне сповіщення в той самий чат із точною командою `/approve` - з очікуваного підтвердження. + Discord також відображає спільні кнопки схвалення, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для схвалювачів і розсилання в канали. + Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, + що чат-схвалення недоступні або ручне схвалення є єдиним шляхом. + Якщо нативний runtime схвалень Discord не активний, OpenClaw зберігає + локальний детермінований запит `/approve ` видимим. Якщо + runtime активний, але нативну картку неможливо доставити до жодної цілі, + OpenClaw надсилає запасне повідомлення в той самий чат із точною командою `/approve` + з очікуваного схвалення. - Автентифікація Gateway і визначення підтвердження дотримуються спільного контракту клієнта Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID через `exec.approval.resolve`). За замовчуванням термін дії підтверджень минає через 30 хвилин. + Автентифікація Gateway і розв’язання схвалень відповідають спільному контракту клієнта Gateway (ID `plugin:` розв’язуються через `plugin.approval.resolve`; інші ID через `exec.approval.resolve`). Типово термін дії схвалень спливає через 30 хвилин. - Див. [Підтвердження виконання](/uk/tools/exec-approvals). + Див. [Схвалення виконання](/uk/tools/exec-approvals). ## Інструменти та шлюзи дій -Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. +Дії з повідомленнями Discord охоплюють обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. Основні приклади: @@ -1083,25 +1102,25 @@ Slash-команди `/model` і `/models` відкривають інтерак - модерація: `timeout`, `kick`, `ban` - присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або локальний шлях до файлу), щоб установити зображення обкладинки запланованої події. +Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла), щоб задати зображення обкладинки запланованої події. Шлюзи дій розташовані в `channels.discord.actions.*`. -Стандартна поведінка шлюзів: +Типова поведінка шлюзів: -| Група дій | Стандартно | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | -| roles | вимкнено | -| moderation | вимкнено | -| presence | вимкнено | +| Група дій | Типово | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | +| roles | вимкнено | +| moderation | вимкнено | +| presence | вимкнено | ## UI Components v2 -OpenClaw використовує компоненти Discord v2 для підтверджень виконання та маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для власного UI (розширене використання; потребує створення payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. +OpenClaw використовує Discord components v2 для схвалень виконання та маркерів між контекстами. Дії з повідомленнями Discord також можуть приймати `components` для власного UI (розширено; потребує створення payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендуються. - `channels.discord.ui.components.accentColor` задає акцентний колір, який використовують контейнери компонентів Discord (hex). -- Задайте для окремого облікового запису через `channels.discord.accounts..ui.components.accentColor`. +- Задайте для кожного облікового запису через `channels.discord.accounts..ui.components.accentColor`. - `embeds` ігноруються, коли присутні components v2. Приклад: @@ -1122,20 +1141,20 @@ OpenClaw використовує компоненти Discord v2 для під ## Голос -Discord має дві окремі голосові поверхні: **голосові канали** реального часу (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду хвилі). Gateway підтримує обидві. +Discord має дві окремі голосові поверхні: realtime **голосові канали** (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду з хвильовою формою). Gateway підтримує обидві. ### Голосові канали Контрольний список налаштування: 1. Увімкніть Message Content Intent у Discord Developer Portal. -2. Увімкніть Server Members Intent, коли використовуються списки дозволених ролей/користувачів. -3. Запросіть бота зі scopes `bot` і `applications.commands`. -4. Надайте дозволи Connect, Speak, Send Messages і Read Message History у цільовому голосовому каналі. +2. Увімкніть Server Members Intent, коли використовуються списки дозволів ролей/користувачів. +3. Запросіть бота зі скоупами `bot` і `applications.commands`. +4. Надайте Connect, Speak, Send Messages і Read Message History у цільовому голосовому каналі. 5. Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). 6. Налаштуйте `channels.discord.voice`. -Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує стандартного агента облікового запису та дотримується тих самих правил списків дозволених і групової політики, що й інші команди Discord. +Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує типового агента облікового запису та дотримується тих самих правил списків дозволів і групових політик, що й інші команди Discord. ```bash /vc join channel: @@ -1175,36 +1194,36 @@ Discord має дві окремі голосові поверхні: **голо Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- `voice.model` перевизначає LLM, який використовується лише для відповідей голосового каналу Discord. Залиште його незаданим, щоб успадкувати модель маршрутизованого агента. +- `voice.model` перевизначає LLM, що використовується лише для відповідей у голосових каналах Discord. Залиште незаданим, щоб успадкувати модель маршрутизованого агента. - STT використовує `tools.media.audio`; `voice.model` не впливає на транскрибування. -- Перевизначення `systemPrompt` для окремого каналу Discord застосовуються до реплік голосової транскрипції для цього голосового каналу. -- Репліки голосової транскрипції визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад `gateway` і `cron`). -- Голос Discord є opt-in для конфігурацій лише з текстом; задайте `channels.discord.voice.enabled=true` (або залиште наявний блок `channels.discord.voice`), щоб увімкнути команди `/vc`, голосове середовище виконання та Gateway intent `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` може явно перевизначити підписку на voice-state intent. Залиште його незаданим, щоб intent відповідав ефективному ввімкненню голосу. -- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів приєднання `@discordjs/voice`. -- Стандартні значення `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. -- `voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб автоматичного приєднання. Стандартно: `30000`. -- `voice.reconnectGraceMs` керує тим, як довго OpenClaw чекає, поки від’єднана голосова сесія почне перепідключення, перш ніж знищити її. Стандартно: `15000`. -- OpenClaw також відстежує помилки дешифрування під час приймання та автоматично відновлюється, виходячи з голосового каналу й повторно приєднуючись після повторних помилок у короткому вікні. -- Якщо після оновлення журнали приймання багаторазово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Убудована лінійка `@discordjs/voice` містить upstream-виправлення padding з PR discord.js #11449, яке закрило issue discord.js #11419. +- Перевизначення Discord `systemPrompt` для окремих каналів застосовуються до ходів голосової транскрипції для цього голосового каналу. +- Ходи голосової транскрипції отримують статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад `gateway` і `cron`). +- Голос Discord є opt-in для текстових конфігурацій; задайте `channels.discord.voice.enabled=true` (або залиште наявний блок `channels.discord.voice`), щоб увімкнути команди `/vc`, голосовий runtime та gateway intent `GuildVoiceStates`. +- `channels.discord.intents.voiceStates` може явно перевизначити підписку на voice-state intent. Залиште незаданим, щоб intent відповідав ефективному ввімкненню голосу. +- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються в параметри приєднання `@discordjs/voice`. +- Типові значення `@discordjs/voice`, якщо не задано: `daveEncryption=true` і `decryptionFailureTolerance=24`. +- `voice.connectTimeoutMs` керує початковим очікуванням Ready у `@discordjs/voice` для `/vc join` і спроб автоматичного приєднання. Типово: `30000`. +- `voice.reconnectGraceMs` керує тим, як довго OpenClaw чекає, поки від’єднана голосова сесія почне повторне підключення, перш ніж її знищити. Типово: `15000`. +- OpenClaw також відстежує помилки розшифрування приймання й автоматично відновлюється, виходячи з голосового каналу та повторно приєднуючись після повторюваних помилок у короткому вікні. +- Якщо після оновлення журнали приймання неодноразово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінійка `@discordjs/voice` містить upstream-виправлення padding із PR discord.js #11449, яке закрило issue discord.js #11419. Конвеєр голосового каналу: -- Захоплення Discord PCM перетворюється на тимчасовий WAV-файл. +- Захоплення PCM із Discord перетворюється на тимчасовий WAV-файл. - `tools.media.audio` обробляє STT, наприклад `openai/gpt-4o-mini-transcribe`. -- Транскрипт надсилається через вхідний потік Discord і маршрутизацію, тоді як LLM для відповіді працює з політикою голосового виведення, яка приховує інструмент агента `tts` і просить повернути текст, оскільки Discord voice відповідає за фінальне відтворення TTS. -- `voice.model`, якщо задано, перевизначає лише LLM відповіді для цієї репліки голосового каналу. -- `voice.tts` об’єднується поверх `messages.tts`; отриманий аудіо виводиться в приєднаному каналі. +- Транскрипт надсилається через ingress і маршрутизацію Discord, тоді як LLM відповіді працює з політикою голосового виводу, яка приховує інструмент агента `tts` і просить повернути текст, оскільки Discord voice відповідає за фінальне TTS-відтворення. +- `voice.model`, коли задано, перевизначає лише LLM відповіді для цього ходу голосового каналу. +- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється в каналі, до якого виконано приєднання. -Облікові дані визначаються для кожного компонента окремо: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. +Облікові дані розв’язуються для кожного компонента: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. ### Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд хвилі та потребують аудіо OGG/Opus. OpenClaw генерує хвилю автоматично, але потребує `ffmpeg` і `ffprobe` на хості Gateway для перевірки та перетворення. +Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw генерує хвильову форму автоматично, але потребує `ffmpeg` і `ffprobe` на хості gateway, щоб перевіряти та конвертувати. -- Надайте **локальний шлях до файлу** (URL відхиляються). -- Не вказуйте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). -- Приймається будь-який аудіоформат; OpenClaw за потреби перетворює його на OGG/Opus. +- Надайте **шлях до локального файла** (URL відхиляються). +- Опустіть текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). +- Приймається будь-який аудіоформат; OpenClaw за потреби конвертує в OGG/Opus. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1216,16 +1235,16 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - увімкніть Message Content Intent - - увімкніть Server Members Intent, коли ви залежите від визначення користувача/учасника + - увімкніть Server Members Intent, коли ви залежите від розв’язання користувачів/учасників - перезапустіть gateway після зміни intents - + - перевірте `groupPolicy` - - перевірте список дозволених guild у `channels.discord.guilds` - - якщо існує мапа `channels` guild, дозволені лише перелічені канали + - перевірте список дозволів guild у `channels.discord.guilds` + - якщо існує мапа `channels` для guild, дозволені лише перелічені канали - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1241,26 +1260,26 @@ openclaw logs --follow Поширені причини: - - `groupPolicy="allowlist"` без відповідного списку дозволених guild/каналу + - `groupPolicy="allowlist"` без відповідного списку дозволів guild/channel - `requireMention` налаштовано в неправильному місці (має бути в `channels.discord.guilds` або записі каналу) - - відправник заблокований списком дозволених `users` guild/каналу + - відправника заблоковано списком дозволів `users` для guild/channel - + Типові журнали: - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Ручки черги Discord gateway: + Регулятори черги Discord gateway: - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` - - це керує лише роботою слухача Discord gateway, а не часом життя репліки агента + - це керує лише роботою listener Discord gateway, а не тривалістю ходу агента - Discord не застосовує тайм-аут, яким володіє канал, до реплік агента в черзі. Слухачі повідомлень передають роботу негайно, а запуски Discord у черзі зберігають порядок у межах сесії, доки життєвий цикл сесії/інструмента/середовища виконання не завершить або не перерве роботу. + Discord не застосовує таймаут, керований каналом, до поставлених у чергу ходів агента. Message listeners одразу передають роботу далі, а поставлені в чергу запуски Discord зберігають порядок у межах сесії, доки життєвий цикл сесії/інструмента/runtime не завершиться або не перерве роботу. ```json5 { @@ -1281,50 +1300,50 @@ openclaw logs --follow - OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартного URL gateway Discord і обмежуються за частотою в журналах. + OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартної URL-адреси gateway Discord і обмежуються за частотою в журналах. - Ручки тайм-ауту метаданих: + Регулятори тайм-ауту метаданих: - один обліковий запис: `channels.discord.gatewayInfoTimeoutMs` - кілька облікових записів: `channels.discord.accounts..gatewayInfoTimeoutMs` - - резервне env, коли config не задано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - стандартно: `30000` (30 секунд), максимум: `120000` + - резервне значення env, коли конфігурацію не задано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - стандарт: `30000` (30 секунд), максимум: `120000` - - OpenClaw очікує на подію Gateway `READY` Discord під час запуску та після повторних підключень у runtime. Налаштування з кількома обліковими записами та поетапним запуском можуть потребувати довшого стартового вікна READY, ніж типове. + + OpenClaw очікує подію Discord gateway `READY` під час запуску та після повторних підключень у runtime. Налаштування з кількома обліковими записами та поетапним запуском можуть потребувати довшого вікна READY під час запуску, ніж стандартне. - Параметри часу очікування READY: + Регулятори тайм-ауту READY: - - запуск з одним обліковим записом: `channels.discord.gatewayReadyTimeoutMs` - - запуск з кількома обліковими записами: `channels.discord.accounts..gatewayReadyTimeoutMs` - - стартовий запасний env, коли конфігурацію не задано: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - - типове значення запуску: `15000` (15 секунд), максимум: `120000` - - runtime з одним обліковим записом: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - runtime з кількома обліковими записами: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - запасний runtime env, коли конфігурацію не задано: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - - типове значення runtime: `30000` (30 секунд), максимум: `120000` + - запуск для одного облікового запису: `channels.discord.gatewayReadyTimeoutMs` + - запуск для кількох облікових записів: `channels.discord.accounts..gatewayReadyTimeoutMs` + - резервне значення env під час запуску, коли конфігурацію не задано: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - стандарт під час запуску: `15000` (15 секунд), максимум: `120000` + - runtime для одного облікового запису: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - runtime для кількох облікових записів: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - резервне значення env для runtime, коли конфігурацію не задано: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - стандарт для runtime: `30000` (30 секунд), максимум: `120000` - - Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. + + Перевірки дозволів `channels status --probe` працюють лише для числових ідентифікаторів каналів. - Якщо ви використовуєте ключі-slug, зіставлення під час runtime усе ще може працювати, але probe не може повністю перевірити дозволи. + Якщо ви використовуєте ключі slug, зіставлення під час runtime усе ще може працювати, але probe не може повністю перевірити дозволи. - + - DM вимкнено: `channels.discord.dm.enabled=false` - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) - - очікування схвалення pairing у режимі `pairing` + - очікування схвалення сполучення в режимі `pairing` - - Типово повідомлення, створені ботами, ігноруються. + + За замовчуванням повідомлення, створені ботами, ігноруються. Якщо ви задаєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. Надавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. @@ -1354,12 +1373,12 @@ openclaw logs --follow - + - підтримуйте OpenClaw актуальним (`openclaw update`), щоб була наявна логіка відновлення приймання голосу Discord - - підтвердьте `channels.discord.voice.daveEncryption=true` (типово) - - почніть із `channels.discord.voice.decryptionFailureTolerance=24` (типове значення upstream) і налаштовуйте лише за потреби - - стежте за журналами на наявність: + - підтвердьте `channels.discord.voice.daveEncryption=true` (стандарт) + - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (стандарт upstream) і налаштовуйте лише за потреби + - стежте в журналах за: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - якщо збої тривають після автоматичного повторного приєднання, зберіть журнали та порівняйте з upstream-історією приймання DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) @@ -1371,49 +1390,49 @@ openclaw logs --follow Основний довідник: [Довідник конфігурації - Discord](/uk/gateway/config-channels#discord). - + -- запуск/автентифікація: `enabled`, `token`, `accounts.*`, `allowBots` +- запуск/auth: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - команда: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` -- черга подій: `eventQueue.listenerTimeout` (бюджет слухача), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- Gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` +- черга подій: `eventQueue.listenerTimeout` (бюджет listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` +- gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -- доставлення: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- потокове передавання: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повторна спроба: `mediaMaxMb` (обмежує вихідні завантаження Discord, типово `100MB`), `retry` +- доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` +- streaming: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повторна спроба: `mediaMaxMb` (обмежує вихідні завантаження Discord, стандарт `100MB`), `retry` - дії: `actions.*` - присутність: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- функції: `threadBindings`, верхньорівневий `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- функції: `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`. ## Пов’язане - - Зв’яжіть користувача Discord із gateway. + + Сполучіть користувача Discord із gateway. - - Поведінка групового чату й allowlist. + + Поведінка групового чату та allowlist. - + Маршрутизуйте вхідні повідомлення до агентів. - + Модель загроз і посилення захисту. - + Зіставляйте guilds і канали з агентами. - + Поведінка нативних команд. diff --git a/docs/uk/channels/slack.md b/docs/uk/channels/slack.md index 0ad145dc0..696ee3326 100644 --- a/docs/uk/channels/slack.md +++ b/docs/uk/channels/slack.md @@ -1,28 +1,28 @@ --- read_when: - - Налаштування Slack або налагодження режиму сокета/HTTP для Slack -summary: Налаштування Slack і поведінка під час виконання (режим сокетів + URL-адреси HTTP-запитів) + - Налаштування Slack або налагодження сокетного/HTTP-режиму Slack +summary: Налаштування Slack і поведінка під час виконання (режим Socket + URL-адреси HTTP-запитів) title: Slack x-i18n: - generated_at: "2026-05-03T22:49:31Z" + generated_at: "2026-05-04T07:02:44Z" model: gpt-5.5 provider: openai - source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b + source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 source_path: channels/slack.md workflow: 16 --- -Готово до production-використання для DM і каналів через інтеграції Slack app. Режим за замовчуванням — Socket Mode; HTTP Request URLs також підтримуються. +Готово до production-використання для DM і каналів через інтеграції застосунку Slack. Режим за замовчуванням — Socket Mode; URL-адреси HTTP-запитів також підтримуються. - - Slack DM за замовчуванням використовують режим сполучення. + + DM у Slack за замовчуванням використовують режим спарювання. Нативна поведінка команд і каталог команд. - - Міжканальна діагностика й інструкції з відновлення. + + Міжканальна діагностика та сценарії відновлення. @@ -31,13 +31,13 @@ x-i18n: - - У налаштуваннях Slack app натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: + + У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: - - виберіть **from a manifest** і виберіть робочий простір для свого app + - виберіть **from a manifest** і виберіть workspace для свого застосунку - вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче й продовжте створення - згенеруйте **App-Level Token** (`xapp-...`) з `connections:write` - - установіть app і скопіюйте показаний **Bot Token** (`xoxb-...`) + - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,15 +84,15 @@ openclaw gateway - + - - У налаштуваннях Slack app натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: + + У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: - - виберіть **from a manifest** і виберіть робочий простір для свого app + - виберіть **from a manifest** і виберіть workspace для свого застосунку - вставте [приклад маніфесту](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням - збережіть **Signing Secret** для перевірки запитів - - установіть app і скопіюйте показаний **Bot Token** (`xoxb-...`) + - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) @@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Використовуйте унікальні шляхи Webhook для HTTP з кількома обліковими записами + Використовуйте унікальні шляхи webhook для HTTP із кількома обліковими записами Надайте кожному обліковому запису окремий `webhookPath` (за замовчуванням `/slack/events`), щоб реєстрації не конфліктували. - + ```bash openclaw gateway @@ -142,7 +142,7 @@ openclaw gateway ## Налаштування транспорту Socket Mode -OpenClaw за замовчуванням установлює час очікування pong для клієнта Slack SDK у 15 секунд для Socket Mode. Перевизначайте параметри транспорту лише тоді, коли потрібне налаштування для конкретного робочого простору або хоста: +OpenClaw за замовчуванням встановлює для клієнта Slack SDK тайм-аут pong у 15 секунд для Socket Mode. Перевизначайте параметри транспорту лише тоді, коли потрібне налаштування для конкретного workspace або хоста: ```json5 { @@ -159,11 +159,11 @@ OpenClaw за замовчуванням установлює час очіку } ``` -Використовуйте це лише для робочих просторів Socket Mode, які журналюють тайм-аути Slack websocket pong/server-ping, або для хостів із відомим виснаженням циклу подій. `clientPingTimeout` — це очікування pong після того, як SDK надсилає клієнтський ping; `serverPingTimeout` — це очікування ping від сервера Slack. Повідомлення app і події залишаються станом застосунку, а не сигналами працездатності транспорту. +Використовуйте це лише для workspace у Socket Mode, які реєструють тайм-аути pong/server-ping websocket Slack або працюють на хостах із відомим голодуванням event loop. `clientPingTimeout` — це очікування pong після того, як SDK надсилає клієнтський ping; `serverPingTimeout` — це очікування ping від сервера Slack. Повідомлення та події застосунку залишаються станом застосунку, а не сигналами працездатності транспорту. ## Контрольний список маніфесту й scope -Базовий маніфест Slack app однаковий для Socket Mode і HTTP Request URLs. Відрізняється лише блок `settings` (і `url` для slash-команди). +Базовий маніфест застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` slash-команди). Базовий маніфест (Socket Mode за замовчуванням): @@ -240,7 +240,7 @@ OpenClaw за замовчуванням установлює час очіку } ``` -Для режиму **HTTP Request URLs** замініть `settings` на HTTP-варіант і додайте `url` до кожної slash-команди. Потрібна публічна URL-адреса: +Для режиму **URL-адрес HTTP-запитів** замініть `settings` на HTTP-варіант і додайте `url` до кожної slash-команди. Потрібна публічна URL-адреса: ```json { @@ -284,16 +284,16 @@ OpenClaw за замовчуванням установлює час очіку ### Додаткові налаштування маніфесту -Увімкніть інші функції, які розширюють наведені вище значення за замовчуванням. +Увімкніть інші функції, що розширюють наведені вище значення за замовчуванням. -Маніфест за замовчуванням вмикає вкладку **Home** у Slack App Home і підписується на `app_home_opened`. Коли учасник робочого простору відкриває вкладку Home, OpenClaw публікує безпечне подання Home за замовчуванням через `views.publish`; жодне корисне навантаження розмови або приватна конфігурація не включається. Вкладка **Messages** залишається ввімкненою для Slack DM. +Маніфест за замовчуванням вмикає вкладку Slack App Home **Home** і підписується на `app_home_opened`. Коли учасник workspace відкриває вкладку Home, OpenClaw публікує безпечний стандартний вигляд Home через `views.publish`; payload розмови або приватна конфігурація не включаються. Вкладка **Messages** залишається ввімкненою для DM у Slack. - Кілька [нативних slash-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами: + Кілька [нативних slash-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з нюансами: - - Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована. + - Використовуйте `/agentstatus` замість `/status`, бо команда `/status` зарезервована. - Одночасно можна зробити доступними не більше 25 slash-команд. Замініть наявний розділ `features.slash_commands` підмножиною [доступних команд](/uk/tools/slash-commands#command-list): @@ -422,7 +422,7 @@ OpenClaw за замовчуванням установлює час очіку ``` - + Використовуйте той самий список `slash_commands`, що й для Socket Mode вище, і додайте `"url": "https://gateway-host.example.com/slack/events"` до кожного запису. Приклад: ```json @@ -443,20 +443,20 @@ OpenClaw за замовчуванням установлює час очіку } ``` - Повторіть це значення `url` для кожної команди в списку. + Повторіть це значення `url` для кожної команди у списку. - - Додайте scope бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували активну ідентичність агента (власне ім’я користувача та іконку) замість стандартної ідентичності застосунку Slack. + + Додайте область бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власне ім’я користувача та іконку) замість стандартної ідентичності застосунку Slack. - Якщо ви використовуєте іконку emoji, Slack очікує синтаксис `:emoji_name:`. + Якщо ви використовуєте іконку-емодзі, Slack очікує синтаксис `:emoji_name:`. - - Якщо ви налаштовуєте `channels.slack.userToken`, типові scope для читання: + + Якщо ви налаштовуєте `channels.slack.userToken`, типовими областями читання є: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -464,7 +464,7 @@ OpenClaw за замовчуванням установлює час очіку - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (якщо ви покладаєтеся на читання через пошук Slack) + - `search:read` (якщо ви залежите від читання пошуку Slack) @@ -473,25 +473,25 @@ OpenClaw за замовчуванням установлює час очіку - `botToken` + `appToken` потрібні для Socket Mode. - Режим HTTP потребує `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають рядки відкритого тексту - або об’єкти SecretRef. -- Токени конфігурації перевизначають резервне значення env. +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті + рядки або об’єкти SecretRef. +- Токени конфігурації перевизначають резервні значення env. - Резервне значення env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до стандартного облікового запису. -- `userToken` (`xoxp-...`) налаштовується лише в конфігурації (без резервного значення env) і типово має поведінку лише для читання (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного значення env) і типово має поведінку лише для читання (`userTokenReadOnly: true`). Поведінка знімка стану: -- Перевірка облікового запису Slack відстежує поля `*Source` і `*Status` - для кожного облікового запису (`botToken`, `appToken`, `signingSecret`, `userToken`). -- Стан: `available`, `configured_unavailable` або `missing`. +- Інспекція облікового запису Slack відстежує поля `*Source` і `*Status` + для кожних облікових даних (`botToken`, `appToken`, `signingSecret`, `userToken`). +- Стан має значення `available`, `configured_unavailable` або `missing`. - `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef - або інше неінлайнове джерело секретів, але поточний шлях команди/середовища виконання - не зміг отримати фактичне значення. + або інше неінлайнове джерело секрету, але поточна команда чи шлях виконання + не змогли отримати фактичне значення. - У режимі HTTP включено `signingSecretStatus`; у Socket Mode - потрібна пара — `botTokenStatus` + `appTokenStatus`. + обов’язкова пара — `botTokenStatus` + `appTokenStatus`. -Для дій/читання каталогу токен користувача може мати пріоритет, якщо його налаштовано. Для запису токен бота лишається пріоритетним; записи через токен користувача дозволені лише коли `userTokenReadOnly: false` і токен бота недоступний. +Для дій і читання каталогу перевага може надаватися токену користувача, якщо його налаштовано. Для запису пріоритетним залишається токен бота; записи через токен користувача дозволені лише коли `userTokenReadOnly: false` і токен бота недоступний. ## Дії та шлюзи @@ -510,15 +510,15 @@ OpenClaw за замовчуванням установлює час очіку Поточні дії повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ID файлів Slack, показані у вхідних заповнювачах файлів, і повертає попередні перегляди зображень для зображень або метадані локального файлу для інших типів файлів. -## Керування доступом і маршрутизація +## Контроль доступу та маршрутизація - - `channels.slack.dmPolicy` керує доступом до DM. `channels.slack.allowFrom` — канонічний список дозволених для DM. + + `channels.slack.dmPolicy` керує доступом до DM. `channels.slack.allowFrom` — канонічний allowlist для DM. - `pairing` (типово) - `allowlist` - - `open` (потребує, щоб `channels.slack.allowFrom` містив `"*"`) + - `open` (вимагає, щоб `channels.slack.allowFrom` містив `"*"`) - `disabled` Прапорці DM: @@ -527,41 +527,41 @@ OpenClaw за замовчуванням установлює час очіку - `channels.slack.allowFrom` - `dm.allowFrom` (застаріле) - `dm.groupEnabled` (групові DM типово false) - - `dm.groupChannels` (необов’язковий список дозволених MPIM) + - `dm.groupChannels` (необов’язковий allowlist MPIM) Пріоритетність для кількох облікових записів: - `channels.slack.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - - Іменовані облікові записи успадковують `channels.slack.allowFrom`, коли власний `allowFrom` не задано. + - Іменовані облікові записи успадковують `channels.slack.allowFrom`, коли їхній власний `allowFrom` не задано. - Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`. - Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли може зробити це без зміни доступу. + Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` досі читаються для сумісності. `openclaw doctor --fix` переносить їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. - Сполучення в DM використовує `openclaw pairing approve slack `. + Pairing у DM використовує `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` керує обробкою каналів: - `open` - `allowlist` - `disabled` - Список дозволених каналів міститься в `channels.slack.channels` і **має використовувати стабільні ID каналів Slack** (наприклад `C12345678`) як ключі конфігурації. + Allowlist каналів розміщується в `channels.slack.channels` і **має використовувати стабільні ID каналів Slack** (наприклад, `C12345678`) як ключі конфігурації. - Примітка щодо середовища виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), середовище виконання переходить до `groupPolicy="allowlist"` і записує попередження в журнал (навіть якщо `channels.defaults.groupPolicy` задано). + Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується резервне `groupPolicy="allowlist"` і записується попередження (навіть якщо `channels.defaults.groupPolicy` задано). - Розв’язання назви/ID: + Розв’язання імені/ID: - - записи списку дозволених каналів і записи списку дозволених DM розв’язуються під час запуску, коли доступ токена це дозволяє + - записи allowlist каналів і записи allowlist DM розв’язуються під час запуску, коли доступ токена це дозволяє - нерозв’язані записи назв каналів зберігаються як налаштовані, але типово ігноруються для маршрутизації - - вхідна авторизація й маршрутизація каналів типово спершу використовують ID; пряме зіставлення імені користувача/slug потребує `channels.slack.dangerouslyAllowNameMatching: true` + - вхідна авторизація та маршрутизація каналів типово спершу використовують ID; пряме зіставлення імені користувача/slug вимагає `channels.slack.dangerouslyAllowNameMatching: true` - Ключі на основі назви (`#channel-name` або `channel-name`) **не** збігаються за `groupPolicy: "allowlist"`. Пошук каналу типово спершу використовує ID, тому ключ на основі назви ніколи не маршрутизуватиметься успішно, а всі повідомлення в цьому каналі буде тихо заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, і ключ на основі назви здається робочим. + Ключі на основі імен (`#channel-name` або `channel-name`) **не** збігаються за `groupPolicy: "allowlist"`. Пошук каналу типово спершу використовує ID, тому ключ на основі імені ніколи не маршрутизуватиметься успішно, і всі повідомлення в цьому каналі буде мовчки заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, а ключ на основі імені здається робочим. - Завжди використовуйте ID каналу Slack як ключ. Щоб його знайти: клацніть канал у Slack правою кнопкою → **Copy link** — ID (`C...`) з’явиться наприкінці URL. + Завжди використовуйте ID каналу Slack як ключ. Щоб знайти його: клацніть канал у Slack правою кнопкою миші → **Copy link** — ID (`C...`) з’являється в кінці URL. Правильно: @@ -578,7 +578,7 @@ OpenClaw за замовчуванням установлює час очіку } ``` - Неправильно (тихо блокується за `groupPolicy: "allowlist"`): + Неправильно (тихо заблоковано за `groupPolicy: "allowlist"`): ```json5 { @@ -597,47 +597,47 @@ OpenClaw за замовчуванням установлює час очіку - Повідомлення каналів типово обмежуються згадками. + Повідомлення каналів за замовчуванням допускаються лише за наявності згадки. Джерела згадок: - явна згадка застосунку (`<@botId>`) - згадка групи користувачів Slack (``), коли користувач-бот є учасником цієї групи користувачів; потребує `usergroups:read` - - regex-шаблони згадок (`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` (список дозволених) + - `users` (allowlist) - `allowBots` - `skills` - `systemPrompt` - `tools`, `toolsBySender` - формат ключа `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або wildcard `"*"` - (застарілі ключі без префікса досі зіставляються лише з `id:`) + (застарілі ключі без префікса й далі зіставляються лише з `id:`) - `allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, створені ботом, приймаються лише коли бот-відправник явно вказаний у списку дозволених `users` цієї кімнати або коли принаймні один явний ID власника Slack з `channels.slack.allowFrom` наразі є учасником кімнати. Wildcard і записи власників за відображуваним іменем не задовольняють присутність власника. Присутність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідний scope читання для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, створене ботом. + `allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, створені ботом, приймаються лише тоді, коли бот-відправник явно вказаний в allowlist `users` цієї кімнати, або коли принаймні один явний ідентифікатор власника Slack з `channels.slack.allowFrom` зараз є учасником кімнати. Wildcard і записи власника за відображуваним іменем не задовольняють наявність власника. Наявність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідний scope читання для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, створене ботом. -## Потоки, сеанси та теги відповіді +## Треди, сеанси й теги відповіді -- DM маршрутизуються як `direct`; канали як `channel`; MPIM як `group`. -- Прив’язки маршрутів Slack приймають необроблені ID учасників, а також форми цілей Slack, як-от `channel:C12345678`, `user:U12345678` і `<@U12345678>`. -- Із типовим `session.dmScope=main` DM Slack згортаються до головного сеансу агента. +- Особисті повідомлення маршрутизуються як `direct`; канали як `channel`; багатокористувацькі особисті повідомлення як `group`. +- Прив'язки маршрутів Slack приймають сирі ідентифікатори співрозмовників, а також форми цілі Slack, як-от `channel:C12345678`, `user:U12345678` і `<@U12345678>`. +- З типовим `session.dmScope=main` особисті повідомлення Slack згортаються до основного сеансу агента. - Сеанси каналів: `agent::slack:channel:`. -- Відповіді в потоках можуть створювати суфікси сеансу потоку (`:thread:`), коли застосовно. +- Відповіді в тредах можуть створювати суфікси сеансу треду (`: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.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.dm.replyToMode` +- застарілий резервний варіант для прямих чатів: `channels.slack.dm.replyToMode` Підтримуються ручні теги відповіді: @@ -645,45 +645,64 @@ OpenClaw за замовчуванням установлює час очіку - `[[reply_to:]]` -`replyToMode="off"` вимикає **всі** потоки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"`. Потоки Slack приховують повідомлення з каналу, тоді як відповіді Telegram лишаються видимими inline. +`replyToMode="off"` вимикає **всі** треди відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги й далі враховуються в режимі `"off"`. Треди Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими в рядку. ## Реакції підтвердження `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. -Порядок розв’язання: +Порядок розв'язання: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- резервне emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") +- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: -- Slack очікує shortcodes (наприклад `"eyes"`). +- Slack очікує shortcode (наприклад, `"eyes"`). - Використовуйте `""`, щоб вимкнути реакцію для облікового запису Slack або глобально. -## Текстове потокове передавання +## Потокове передавання тексту -`channels.slack.streaming` керує поведінкою живого попереднього перегляду: +`channels.slack.streaming` керує поведінкою live preview: -- `off`: вимкнути потокове передавання живого попереднього перегляду. -- `partial` (типово): замінювати текст попереднього перегляду найновішим частковим виводом. -- `block`: додавати chunked-оновлення попереднього перегляду. -- `progress`: показувати текст стану прогресу під час генерування, а потім надіслати фінальний текст. -- `streaming.preview.toolProgress`: коли чернетка попереднього перегляду активна, маршрутизувати оновлення інструментів/прогресу в те саме відредаговане повідомлення попереднього перегляду (типово: `true`). Задайте `false`, щоб зберігати окремі повідомлення інструментів/прогресу. +- `off`: вимкнути потокове передавання live preview. +- `partial` (типово): замінювати текст preview найновішим частковим виводом. +- `block`: додавати фрагментовані оновлення preview. +- `progress`: показувати текст статусу перебігу під час генерування, а потім надіслати фінальний текст. +- `streaming.preview.toolProgress`: коли draft preview активний, спрямовувати оновлення інструментів/перебігу в те саме редаговане повідомлення preview (типово: `true`). Установіть `false`, щоб зберігати окремі повідомлення інструментів/перебігу. +- `streaming.preview.commandText` / `streaming.progress.commandText`: установіть `status`, щоб зберігати компактні рядки перебігу інструментів, приховуючи сирий текст команд/виконання (типово: `raw`). -`channels.slack.streaming.nativeTransport` керує нативним текстовим потоковим передаванням Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`). +Приховати сирий текст команд/виконання, зберігаючи компактні рядки перебігу: -- Потік відповіді має бути доступний, щоб з’являлися нативне текстове потокове передавання й стан потоку асистента Slack. Вибір потоку все одно відповідає `replyToMode`. -- Канали, групові чати й корені DM верхнього рівня досі можуть використовувати звичайну чернетку попереднього перегляду, коли нативне потокове передавання недоступне або потоку відповіді немає. -- DM Slack верхнього рівня типово лишаються поза потоком, тому вони не показують thread-style нативний stream/status попередній перегляд Slack; натомість OpenClaw публікує й редагує чернетку попереднього перегляду в DM. -- Медіа та нетекстові payload повертаються до звичайної доставки. -- Фінальні медіа/помилки скасовують очікувані редагування попереднього перегляду; придатні текстові/block фінали flush лише тоді, коли можуть відредагувати попередній перегляд на місці. -- Якщо потокове передавання переривається посеред відповіді, OpenClaw повертається до звичайної доставки для решти payload. +```json +{ + "channels": { + "slack": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` -Використовуйте чернетку попереднього перегляду замість нативного текстового потокового передавання Slack: +`channels.slack.streaming.nativeTransport` керує нативним потоковим передаванням тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`). + +- Для появи нативного потокового передавання тексту й статусу треду асистента Slack має бути доступний тред відповіді. Вибір треду й далі дотримується `replyToMode`. +- Канали, групові чати й кореневі повідомлення особистих повідомлень верхнього рівня й далі можуть використовувати звичайний draft preview, коли нативне потокове передавання недоступне або тред відповіді не існує. +- Особисті повідомлення Slack верхнього рівня за замовчуванням лишаються поза тредом, тому вони не показують нативний stream/status preview у стилі треду Slack; натомість OpenClaw публікує й редагує draft preview в особистому повідомленні. +- Медіа й нетекстові payload повертаються до звичайної доставки. +- Фінальні медіа/помилки скасовують очікувані редагування preview; придатні фінальні тексти/блоки скидаються лише тоді, коли можуть редагувати preview на місці. +- Якщо потокове передавання зазнає помилки посеред відповіді, OpenClaw повертається до звичайної доставки для решти payload. + +Використовувати draft preview замість нативного потокового передавання тексту Slack: ```json5 { @@ -704,54 +723,54 @@ OpenClaw за замовчуванням установлює час очіку - boolean `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 обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в тредах, які використовують стандартний індикатор стану "набирає текст...". -Порядок розв’язання: +Порядок вирішення: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` Примітки: -- Slack очікує шорткоди (наприклад `"hourglass_flowing_sand"`). -- Реакція виконується за принципом best-effort, а очищення автоматично пробується після завершення відповіді або шляху помилки. +- Slack очікує короткі коди (наприклад `"hourglass_flowing_sand"`). +- Реакція виконується за принципом найкращих зусиль, а очищення автоматично виконується після завершення відповіді або шляху помилки. -## Медіа, поділ на фрагменти та доставлення +## Медіа, розбиття на фрагменти та доставка Файлові вкладення Slack завантажуються з приватних URL, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, коли отримання успішне та обмеження розміру це дозволяють. Заповнювачі файлів містять Slack `fileId`, щоб агенти могли отримати оригінальний файл за допомогою `download-file`. - Завантаження використовують обмежені таймаути простою та загального часу. Якщо отримання файлу Slack зависає або завершується помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу. + Завантаження використовують обмежені тайм-аути простою та загальні тайм-аути. Якщо отримання файлу Slack зависає або завершується помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу. Стандартне обмеження розміру вхідних даних під час виконання становить `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`. - - текстові фрагменти використовують `channels.slack.textChunkLimit` (типово 4000) + - текстові фрагменти використовують `channels.slack.textChunkLimit` (стандартно 4000) - `channels.slack.chunkMode="newline"` вмикає поділ із пріоритетом абзаців - - надсилання файлів використовує API завантаження Slack і може включати відповіді в гілках (`thread_ts`) - - обмеження вихідних медіа відповідає `channels.slack.mediaMaxMb`, якщо налаштовано; інакше надсилання в канал використовує типові значення за MIME-типом із медіаконвеєра + - надсилання файлів використовує API завантаження Slack і може включати відповіді в тредах (`thread_ts`) + - обмеження вихідних медіа дотримується `channels.slack.mediaMaxMb`, коли налаштовано; інакше надсилання в канал використовує стандартні значення MIME-виду з медіаконвеєра - + Бажані явні цілі: - `user:` для DM - `channel:` для каналів - Текстові або лише блокові Slack DM можуть публікуватися безпосередньо за ID користувачів; завантаження файлів і надсилання в гілках спочатку відкривають DM через API розмов Slack, бо ці шляхи потребують конкретного ID розмови. + Текстові або лише блокові DM Slack можуть публікуватися безпосередньо за ID користувачів; завантаження файлів і надсилання в тредах спершу відкривають DM через API розмов Slack, оскільки ці шляхи потребують конкретного ID розмови. ## Команди та поведінка slash -Команди slash з’являються у Slack як одна налаштована команда або кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команд: +Slash-команди відображаються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити стандартні значення команд: - `enabled: false` - `name: "openclaw"` @@ -762,7 +781,7 @@ OpenClaw за замовчуванням установлює час очіку /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. @@ -770,22 +789,22 @@ OpenClaw за замовчуванням установлює час очіку /help ``` -Меню нативних аргументів використовують адаптивну стратегію рендерингу, яка показує модальне підтвердження перед надсиланням вибраного значення опції: +Меню нативних аргументів використовують адаптивну стратегію рендерингу, яка показує модальне підтвердження перед передаванням вибраного значення опції: - до 5 опцій: блоки кнопок - 6-100 опцій: статичне меню вибору -- понад 100 опцій: зовнішній список вибору з асинхронною фільтрацією опцій, коли доступні обробники параметрів інтерактивності -- перевищено обмеження Slack: закодовані значення опцій повертаються до кнопок +- понад 100 опцій: зовнішній вибір з асинхронною фільтрацією опцій, коли доступні обробники параметрів інтерактивності +- перевищено ліміти Slack: закодовані значення опцій повертаються до кнопок ```txt /think ``` -Сесії slash використовують ізольовані ключі, як-от `agent::slack:slash:`, і все одно спрямовують виконання команд до цільової сесії розмови за допомогою `CommandTargetSessionKey`. +Slash-сесії використовують ізольовані ключі на кшталт `agent::slack:slash:` і все одно спрямовують виконання команд до цільової сесії розмови за допомогою `CommandTargetSessionKey`. ## Інтерактивні відповіді -Slack може рендерити створені агентом інтерактивні елементи керування відповіддю, але ця функція типово вимкнена. +Slack може відображати створені агентом інтерактивні елементи керування відповідями, але ця функція стандартно вимкнена. Увімкніть її глобально: @@ -819,44 +838,44 @@ Slack може рендерити створені агентом інтерак } ``` -Коли ввімкнено, агенти можуть виводити директиви відповідей лише для Slack: +Коли ввімкнено, агенти можуть видавати директиви відповідей лише для Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Ці директиви компілюються у Slack Block Kit і спрямовують кліки або вибори назад через наявний шлях подій взаємодії Slack. +Ці директиви компілюються в Slack Block Kit і спрямовують кліки або вибори назад через наявний шлях подій взаємодії Slack. Примітки: -- Це UI, специфічний для Slack. Інші канали не перетворюють директиви Slack Block Kit на власні системи кнопок. -- Значення інтерактивних callback є непрозорими токенами, згенерованими OpenClaw, а не необробленими значеннями, створеними агентом. -- Якщо згенеровані інтерактивні блоки перевищили б обмеження Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання недійсного payload блоків. +- Це UI, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок. +- Значення інтерактивних callback — це непрозорі токени, згенеровані OpenClaw, а не необроблені значення, створені агентом. +- Якщо згенеровані інтерактивні блоки перевищили б ліміти Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання недійсного корисного навантаження блоків. -## Затвердження Exec у Slack +## Схвалення exec у Slack -Slack може діяти як нативний клієнт затвердження з інтерактивними кнопками та взаємодіями замість повернення до Web UI або термінала. +Slack може працювати як нативний клієнт схвалень з інтерактивними кнопками та взаємодіями, замість повернення до Web UI або термінала. -- Затвердження Exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналу. -- Затвердження Plugin усе ще можуть розв’язуватися через ту саму нативну для Slack поверхню кнопок, коли запит уже потрапляє у Slack і тип ID затвердження є `plugin:`. -- Авторизація затверджувача все одно примусово застосовується: лише користувачі, ідентифіковані як затверджувачі, можуть затверджувати або відхиляти запити через Slack. +- Схвалення exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналом. +- Схвалення Plugin усе ще можуть вирішуватися через ту саму нативну поверхню кнопок Slack, коли запит уже потрапляє в Slack, а вид ID схвалення — `plugin:`. +- Авторизація схвалювача все одно застосовується: лише користувачі, визначені як схвалювачі, можуть схвалювати або відхиляти запити через Slack. -Це використовує ту саму спільну поверхню кнопок затвердження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашої програми Slack, запити на затвердження рендеряться як кнопки Block Kit безпосередньо в розмові. -Коли ці кнопки присутні, вони є основним UX затвердження; OpenClaw -має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що -затвердження через чат недоступні або ручне затвердження є єдиним шляхом. +Це використовує ту саму спільну поверхню кнопок схвалення, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на схвалення відображаються як кнопки Block Kit безпосередньо в розмові. +Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw +має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що чат-схвалення +недоступні або ручне схвалення є єдиним шляхом. Шлях конфігурації: - `channels.slack.execApprovals.enabled` - `channels.slack.execApprovals.approvers` (необов’язково; за можливості повертається до `commands.ownerAllowFrom`) -- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) +- `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: +Стандартна поведінка без явної конфігурації схвалень exec для Slack: ```json5 { @@ -866,8 +885,8 @@ Slack автоматично вмикає нативні затвердженн } ``` -Явна нативна конфігурація Slack потрібна лише тоді, коли потрібно перевизначити затверджувачів, додати фільтри або -увімкнути доставлення до початкового чату: +Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити схвалювачів, додати фільтри або +увімкнути доставку в початковий чат: ```json5 { @@ -883,24 +902,24 @@ Slack автоматично вмикає нативні затвердженн } ``` -Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити на затвердження Exec також мають +Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити схвалення exec також мають маршрутизуватися до інших чатів або явних позасмугових цілей. Спільне переспрямування `approvals.plugin` також -окреме; нативні кнопки Slack усе ще можуть розв’язувати затвердження Plugin, коли ці запити вже потрапляють +окреме; нативні кнопки Slack все ще можуть вирішувати схвалення Plugin, коли ці запити вже потрапляють у Slack. -`/approve` у тому самому чаті також працює в каналах Slack і DM, які вже підтримують команди. Див. [Затвердження Exec](/uk/tools/exec-approvals), щоб отримати повну модель переспрямування затверджень. +`/approve` у тому самому чаті також працює в каналах Slack і DM, які вже підтримують команди. Див. [Схвалення exec](/uk/tools/exec-approvals), щоб ознайомитися з повною моделлю переспрямування схвалень. ## Події та операційна поведінка -- Редагування й видалення повідомлень відображаються у системні події. -- Трансляції гілок (відповіді в гілках «Також надіслати до каналу») обробляються як звичайні повідомлення користувача. -- Події додавання/видалення реакцій відображаються у системні події. -- Події приєднання/виходу учасника, створення/перейменування каналу та додавання/видалення закріплення відображаються у системні події. +- Редагування/видалення повідомлень відображаються в системні події. +- Трансляції тредів (відповіді в треді "Також надіслати в канал") обробляються як звичайні повідомлення користувачів. +- Події додавання/видалення реакцій відображаються в системні події. +- Події приєднання/виходу учасника, створення/перейменування каналу та додавання/видалення закріплення відображаються в системні події. - `channel_id_changed` може мігрувати ключі конфігурації каналу, коли `configWrites` увімкнено. -- Метадані теми/призначення каналу розглядаються як недовірений контекст і можуть вводитися в контекст маршрутизації. -- Початкове повідомлення гілки та засівання початкового контексту історії гілки фільтруються налаштованими списками дозволених відправників, коли застосовно. -- Дії блоків і модальні взаємодії створюють структуровані системні події `Slack interaction: ...` з насиченими полями payload: - - дії блоків: вибрані значення, мітки, значення засобів вибору та метадані `workflow_*` +- Метадані теми/призначення каналу вважаються недовіреним контекстом і можуть бути інжектовані в контекст маршрутизації. +- Початковий допис треду та початкове заповнення контексту історії треду фільтруються налаштованими списками дозволених відправників, коли це застосовно. +- Дії блоків і модальні взаємодії створюють структуровані системні події `Slack interaction: ...` з насиченими полями корисного навантаження: + - дії блоків: вибрані значення, мітки, значення вибирача та метадані `workflow_*` - події модальних `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеннями форми ## Довідник конфігурації @@ -913,8 +932,8 @@ Slack автоматично вмикає нативні затвердженн - доступ до DM: `dm.enabled`, `dmPolicy`, `allowFrom` (застаріле: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - перемикач сумісності: `dangerouslyAllowNameMatching` (break-glass; тримайте вимкненим, якщо не потрібно) - доступ до каналу: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- гілки/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` +- треди/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - операції/функції: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -923,10 +942,10 @@ Slack автоматично вмикає нативні затвердженн - Перевірте за порядком: + Перевірте по порядку: - `groupPolicy` - - список дозволених каналів (`channels.slack.channels`) — **ключі мають бути ID каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв тихо не спрацьовують за `groupPolicy: "allowlist"`, бо маршрутизація каналів типово насамперед спирається на ID. Щоб знайти ID: клацніть канал у Slack правою кнопкою → **Копіювати посилання** — значення `C...` у кінці URL є ID каналу. + - список дозволених каналів (`channels.slack.channels`) — **ключі мають бути ID каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв непомітно не спрацьовують із `groupPolicy: "allowlist"`, оскільки маршрутизація каналів стандартно спершу використовує ID. Щоб знайти ID: клацніть канал у Slack правою кнопкою → **Копіювати посилання** — значення `C...` наприкінці URL є ID каналу. - `requireMention` - поканальний список дозволених `users` @@ -945,9 +964,9 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`) - - затвердження сполучення / записи списку дозволених + - схвалення спарювання / записи списку дозволених - події DM Slack Assistant: докладні журнали зі згадкою `drop message_changed` - зазвичай означають, що Slack надіслав відредаговану подію гілки Assistant без + зазвичай означають, що Slack надіслав відредаговану подію треду Assistant без відновлюваного людського відправника в метаданих повідомлення ```bash @@ -957,96 +976,96 @@ openclaw pairing list slack - Перевірте токени бота й програми та ввімкнення Socket Mode у налаштуваннях програми Slack. + Перевірте токени бота й застосунку та ввімкнення Socket Mode у налаштуваннях застосунку Slack. Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або `appTokenStatus: "configured_unavailable"`, обліковий запис Slack - налаштовано, але поточне середовище виконання не змогло визначити значення, + налаштований, але поточне середовище виконання не змогло визначити значення, підкріплене SecretRef. - + Перевірте: - секрет підпису - шлях Webhook - - URL запитів Slack (події + інтерактивність + команди slash) + - URL запитів Slack (події + інтерактивність + Slash Commands) - унікальний `webhookPath` для кожного облікового запису HTTP - Якщо `signingSecretStatus: "configured_unavailable"` з’являється у знімках - облікового запису, обліковий запис HTTP налаштовано, але поточне середовище виконання не змогло + Якщо `signingSecretStatus: "configured_unavailable"` з’являється в знімках + облікових записів, обліковий запис HTTP налаштований, але поточне середовище виконання не змогло визначити секрет підпису, підкріплений SecretRef. - - Перевірте, що саме ви мали на меті: + + Перевірте, що саме ви мали намір використати: - - режим нативних команд (`channels.slack.commands.native: true`) з відповідними командами slash, зареєстрованими у Slack - - або режим однієї команди slash (`channels.slack.slashCommand.enabled: true`) + - режим нативних команд (`channels.slack.commands.native: true`) з відповідними slash-командами, зареєстрованими в Slack + - або режим однієї slash-команди (`channels.slack.slashCommand.enabled: true`) Також перевірте `commands.useAccessGroups` і списки дозволених каналів/користувачів. -## Довідник зору для вкладень +## Довідник vision для вкладень -Slack може прикріплювати завантажені медіа до ходу агента, коли завантаження файлів Slack успішне та обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповіді з підтримкою зору; інші файли зберігаються як контекст файлу, доступний для завантаження, а не трактуються як вхідні зображення. +Slack може приєднувати завантажені медіа до ходу агента, коли завантаження файлів Slack успішні та обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповідей з підтримкою vision; інші файли зберігаються як завантажуваний файловий контекст, а не обробляються як вхідні зображення. ### Підтримувані типи медіа -| Тип медіа | Джерело | Поточна поведінка | Примітки | -| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й додаються до ходу для обробки з підтримкою зору | Обмеження на файл: `channels.slack.mediaMaxMb` (типово 20 MB) | -| PDF-файли | URL файлу Slack | Завантажуються й надаються як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідні дані Slack не перетворюють PDF на вхідні дані зображень для зору автоматично | -| Інші файли | URL файлу Slack | Завантажуються, коли це можливо, і надаються як файловий контекст | Двійкові файли не обробляються як вхідні зображення | -| Відповіді в тредах | Файли початкового повідомлення треду | Файли кореневого повідомлення можуть бути гідратовані як контекст, коли відповідь не має прямих медіа | Початкові повідомлення лише з файлами використовують заповнювач вкладення | -| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення | +| Тип медіа | Джерело | Поточна поведінка | Примітки | +| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й долучаються до ходу для обробки з підтримкою зору | Ліміт на файл: `channels.slack.mediaMaxMb` (за замовчуванням 20 MB) | +| Файли PDF | URL файлу Slack | Завантажуються й надаються як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідні повідомлення Slack не перетворюють PDF автоматично на вхідні дані для зору за зображеннями | +| Інші файли | URL файлу Slack | Завантажуються, коли це можливо, і надаються як файловий контекст | Двійкові файли не обробляються як вхідні зображення | +| Відповіді в гілці | Файли початкового повідомлення гілки | Файли кореневого повідомлення можуть бути завантажені як контекст, коли відповідь не має власних медіа | Початкові повідомлення лише з файлами використовують placeholder вкладення | +| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення | ### Вхідний конвеєр -Коли надходить повідомлення Slack із вкладеними файлами: +Коли надходить повідомлення Slack із файловими вкладеннями: 1. OpenClaw завантажує файл із приватної URL-адреси Slack за допомогою токена бота (`xoxb-...`). -2. У разі успіху файл записується до сховища медіа. +2. Після успішного завантаження файл записується до сховища медіа. 3. Шляхи завантажених медіа й типи вмісту додаються до вхідного контексту. -4. Шляхи моделей/інструментів із підтримкою зору можуть використовувати вкладені зображення з цього контексту. +4. Шляхи моделей/інструментів із підтримкою зору можуть використовувати вкладення зображень із цього контексту. 5. Файли, що не є зображеннями, залишаються доступними як файлові метадані або посилання на медіа для інструментів, які можуть їх обробляти. -### Успадкування вкладень кореня треду +### Успадкування вкладень кореня гілки -Коли повідомлення надходить у треді (має батьківський `thread_ts`): +Коли повідомлення надходить у гілці (має батьківський `thread_ts`): -- Якщо сама відповідь не має прямих медіа, а включене кореневе повідомлення має файли, Slack може гідратувати кореневі файли як контекст початкового повідомлення треду. -- Прямі вкладення відповіді мають пріоритет над вкладеннями кореневого повідомлення. -- Кореневе повідомлення, яке має лише файли й не має тексту, представляється заповнювачем вкладення, щоб резервний механізм усе одно міг включити його файли. +- Якщо сама відповідь не має власних медіа, а включене кореневе повідомлення має файли, Slack може завантажити кореневі файли як контекст початкового повідомлення гілки. +- Безпосередні вкладення відповіді мають пріоритет над вкладеннями кореневого повідомлення. +- Кореневе повідомлення, яке має лише файли й не має тексту, представляється placeholder вкладення, щоб fallback усе ще міг включити його файли. ### Обробка кількох вкладень -Коли одне повідомлення Slack містить кілька вкладених файлів: +Коли одне повідомлення Slack містить кілька файлових вкладень: -- Кожне вкладення обробляється незалежно через медіаконвеєр. +- Кожне вкладення обробляється незалежно через конвеєр медіа. - Посилання на завантажені медіа агрегуються в контекст повідомлення. -- Порядок обробки відповідає порядку файлів Slack у корисному навантаженні події. +- Порядок обробки відповідає порядку файлів Slack у payload події. - Помилка завантаження одного вкладення не блокує інші. ### Обмеження розміру, завантаження й моделі -- **Обмеження розміру**: Типово 20 MB на файл. Налаштовується через `channels.slack.mediaMaxMb`. -- **Помилки завантаження**: Файли, які Slack не може надати, прострочені URL-адреси, недоступні файли, завеликі файли та HTML-відповіді автентифікації/входу Slack пропускаються замість повідомлення про непідтримувані формати. +- **Ліміт розміру**: За замовчуванням 20 MB на файл. Налаштовується через `channels.slack.mediaMaxMb`. +- **Помилки завантаження**: Файли, які Slack не може надати, прострочені URL-адреси, недоступні файли, завеликі файли та HTML-відповіді автентифікації/входу Slack пропускаються замість того, щоб повідомлятися як непідтримувані формати. - **Модель зору**: Аналіз зображень використовує активну модель відповіді, якщо вона підтримує зір, або модель зображень, налаштовану в `agents.defaults.imageModel`. ### Відомі обмеження -| Сценарій | Поточна поведінка | Обхідний шлях | -| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| Прострочена URL-адреса файлу Slack | Файл пропускається; помилка не показується | Повторно завантажте файл у Slack | -| Модель зору не налаштована | Вкладені зображення зберігаються як посилання на медіа, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою зору | -| Дуже великі зображення (> 20 MB типово) | Пропускаються відповідно до обмеження розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє | -| Переслані/спільні вкладення | Текст і медіа зображень/файлів, розміщені в Slack, обробляються за принципом найкращого зусилля | Поділіться ними напряму в треді OpenClaw | -| PDF-вкладення | Зберігаються як файловий/медійний контекст, не маршрутизуються автоматично через зір для зображень | Використайте `download-file` для файлових метаданих або інструмент `pdf` для аналізу PDF | +| Сценарій | Поточна поведінка | Обхідний шлях | +| ------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| Прострочена URL-адреса файлу Slack | Файл пропущено; помилка не показується | Повторно завантажте файл у Slack | +| Модель зору не налаштована | Вкладення зображень зберігаються як посилання на медіа, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою зору | +| Дуже великі зображення (> 20 MB за замовчуванням) | Пропускаються згідно з лімітом розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє | +| Переслані/поширені вкладення | Текст і розміщені в Slack медіа зображень/файлів обробляються за best-effort | Поширте повторно безпосередньо в гілці OpenClaw | +| Вкладення PDF | Зберігаються як файловий/медіаконтекст, але не маршрутизуються автоматично через зір за зображеннями | Використайте `download-file` для файлових метаданих або інструмент `pdf` для аналізу PDF | ### Пов’язана документація @@ -1054,13 +1073,13 @@ Slack може прикріплювати завантажені медіа до - [Інструмент PDF](/uk/tools/pdf) - Епік: [#51349](https://github.com/openclaw/openclaw/issues/51349) — увімкнення зору для вкладень Slack - Регресійні тести: [#51353](https://github.com/openclaw/openclaw/issues/51353) -- Жива перевірка: [#51354](https://github.com/openclaw/openclaw/issues/51354) +- Перевірка наживо: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## Пов’язане - Зв’яжіть користувача Slack із Gateway. + Прив’яжіть користувача Slack до Gateway. Поведінка каналів і групових особистих повідомлень. @@ -1072,7 +1091,7 @@ Slack може прикріплювати завантажені медіа до Модель загроз і посилення захисту. - Структура конфігурації та пріоритетність. + Структура конфігурації та пріоритети. Каталог команд і поведінка. diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index db311592f..9dd2b7fcd 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - - Робота з функціями Telegram або Webhook -summary: Статус підтримки, можливості та налаштування бота Telegram + - Робота над функціями Telegram або Webhook +summary: Стан підтримки бота Telegram, можливості та налаштування title: Telegram x-i18n: - generated_at: "2026-05-04T06:12:24Z" + generated_at: "2026-05-04T07:02:42Z" model: gpt-5.5 provider: openai - source_hash: c7f49db5f3fe8fd724e53a2ae3d226446f248bf9d021fcc01c1cf816649381d2 + source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6 source_path: channels/telegram.md workflow: 16 --- -Готово для продакшну для ботів у приватних повідомленнях і групах через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий. +Готово до продакшну для особистих повідомлень ботів і груп через grammY. Long polling є режимом за замовчуванням; режим Webhook необов’язковий. - Типова політика особистих повідомлень для Telegram — сполучення. + Політика особистих повідомлень за замовчуванням для Telegram — сполучення. - - Міжканальна діагностика та інструкції з відновлення. + + Міжканальна діагностика та сценарії відновлення. Повні шаблони й приклади конфігурації каналів. @@ -30,9 +30,9 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я точно `@BotFather`). + Відкрийте Telegram і поспілкуйтеся з **@BotFather** (переконайтеся, що handle саме `@BotFather`). - Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. + Запустіть `/newbot`, дотримуйтеся підказок і збережіть токен. @@ -51,8 +51,8 @@ x-i18n: } ``` - Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. + Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. @@ -69,30 +69,30 @@ openclaw pairing approve telegram - Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. -Порядок визначення токена враховує облікові записи. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним значенням env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. -## Налаштування на боці Telegram +## Налаштування з боку Telegram - Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує групові повідомлення, що їх вони отримують. + Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує групові повідомлення, що вони отримують. - Якщо бот має бачити всі групові повідомлення, виконайте одне з наведеного: + Якщо бот має бачити всі групові повідомлення, або: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. - + Статус адміністратора керується в налаштуваннях групи Telegram. Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. @@ -101,45 +101,45 @@ openclaw pairing approve telegram - - `/setjoingroups`, щоб дозволити або заборонити додавання до груп - - `/setprivacy` для поведінки видимості в групі + - `/setjoingroups`, щоб дозволити/заборонити додавання до груп + - `/setprivacy` для поведінки видимості в групах -## Контроль доступу та активація +## Контроль доступу й активація - `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: + `channels.telegram.dmPolicy` керує доступом через особисті повідомлення: - `pairing` (за замовчуванням) - - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`) - - `open` (потребує, щоб `allowFrom` містив `"*"`) + - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) + - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `dmPolicy: "open"` з `allowFrom: ["*"]` дає будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, змогу керувати ботом. Використовуйте це лише для навмисно публічних ботів із суворо обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. - `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. - У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об’єднання все ще не містить явного wildcard. - `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється перевіркою конфігурації. + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються. + У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня вважається межею безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об’єднання все ще не містить явний wildcard. + `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення й відхиляється валідацією конфігурації. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (за принципом best-effort; потрібен токен бота Telegram). + Якщо ви оновилися і ваша конфігурація містить записи allowlist виду `@username`, запустіть `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram). Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (а не залежала від попередніх схвалень сполучення). + Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (а не залежала від попередніх схвалень сполучення). - Поширена плутанина: схвалення сполучення в особистих повідомленнях не означає «цього відправника авторизовано всюди». - Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також установлює `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. - Авторизація відправників у групах усе ще походить із явних allowlist у конфігурації. - Якщо ви хочете «я авторизований один раз, і працюють і особисті повідомлення, і групові команди», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. + Типова плутанина: схвалення сполучення в особистих повідомленнях не означає «цей відправник авторизований всюди». + Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. + Авторизація відправників у групах усе одно походить із явних allowlist у конфігурації. + Якщо ви хочете «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Напишіть своєму боту в особисті повідомлення. - 2. Виконайте `openclaw logs --follow`. + 1. Надішліть особисте повідомлення своєму боту. + 2. Запустіть `openclaw logs --follow`. 3. Прочитайте `from.id`. Офіційний метод Bot API: @@ -153,15 +153,15 @@ curl "https://api.telegram.org/bot/getUpdates" - Два елементи керування застосовуються разом: + Разом застосовуються два елементи керування: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає конфігурації `groups`: - - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи + - з `groupPolicy: "open"`: будь-яка група може проходити перевірки group-ID - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - - `groups` налаштовано: діє як allowlist (явні ID або `"*"`) + - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) - 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) + 2. **Яким відправникам дозволено писати в групах** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (за замовчуванням) - `disabled` @@ -169,12 +169,12 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень для особистих повідомлень. - Сполучення лишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи чи теми. - Якщо `groupAllowFrom` не встановлено, Telegram повертається до конфігураційного `allowFrom`, а не до сховища сполучень. - Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` невстановленим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням відмовляє безпечно через `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Нечислові записи ігноруються для авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень особистих повідомлень. + Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень. + Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. + Примітка runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -211,11 +211,11 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. + Типова помилка: `groupAllowFrom` не є allowlist груп Telegram. - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. + - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, хто саме в дозволеній групі може запускати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. @@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд рівня сесії: + Перемикачі команд рівня сеансу: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Використовуйте конфігурацію для збереження. + Вони оновлюють лише стан сеансу. Для сталості використовуйте конфігурацію. Приклад сталої конфігурації: @@ -264,20 +264,20 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються у спільний конверт каналу з метаданими відповіді та placeholders для медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми лишалися ізольованими. -- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID треду для відповідей, але за замовчуванням тримає особисті повідомлення у плоскій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій за темами в особистих повідомленнях. -- Довге опитування використовує grammY runner із послідовністю для кожного чату й кожного треду. Загальна паралельність runner sink використовує `agents.defaults.maxConcurrent`. -- Довге опитування захищене всередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній poller використовує той самий токен. -- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується). +- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа. +- Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими. +- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID thread для відповідей, але за замовчуванням тримає особисті повідомлення в плоскому сеансі. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сеансів тем в особистих повідомленнях. +- Long polling використовує grammY runner із послідовністю на чат/на thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. +- Long polling захищений усередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller. +- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через polling-stall під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується). ## Довідник функцій - OpenClaw може транслювати часткові відповіді в реальному часі: + OpenClaw може stream часткові відповіді в реальному часі: - прямі чати: повідомлення попереднього перегляду + `editMessageText` - групи/теми: повідомлення попереднього перегляду + `editMessageText` @@ -285,11 +285,12 @@ curl "https://api.telegram.org/bot/getUpdates" Вимога: - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` зберігає одну редаговану чернетку статусу й оновлює її прогресом інструментів до фінальної доставки - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний preview streaming) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` + - `progress` зберігає один editable чернетковий статус і оновлює його прогресом інструментів до фінальної доставки + - `streaming.preview.toolProgress` керує тим, чи повторно використовують оновлення інструментів/прогресу те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли preview streaming активний) + - `streaming.preview.commandText` керує деталями command/exec у цих рядках прогресу інструментів: `raw` (за замовчуванням, зберігає випущену поведінку) або `status` (лише мітка інструмента) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки статусу, які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram зберігає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки стану, що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,25 +307,60 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення про інструменти/прогрес приглушуються замість надсилання як окремі статусні повідомлення. Запити на схвалення, медіа-вміст і помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно лише зберегти редагування попереднього перегляду відповіді, приховавши статусні рядки прогресу інструментів. + Щоб залишити прогрес інструментів видимим, але приховати текст command/exec, задайте: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "partial", + "preview": { + "commandText": "status" + } + } + } + } + } + ``` + + Для режиму чернетки прогресу розмістіть ту саму політику тексту команди в `streaming.progress`: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальний службовий вивід інструментів і прогресу пригнічується замість надсилання окремими повідомленнями статусу. Запити на схвалення, медіа-навантаження й помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. - Виняток — відповіді на вибрані цитати в Telegram. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний шлях відповіді з цитатою Telegram замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показати короткі статусні рядки для цього ходу. Відповіді на поточне повідомлення без тексту вибраної цитати все ще зберігають потоковий попередній перегляд. Установіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді з цитатами, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс. + Відповіді Telegram на вибрані цитати є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний шлях Telegram для відповіді з цитатою замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показувати короткі рядки статусу для цього ходу. Відповіді на поточне повідомлення без тексту вибраної цитати все ще зберігають потокове передавання попереднього перегляду. Установіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді з цитатами, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс. - Для відповідей лише з текстом: + Для текстових відповідей: - - короткі попередні перегляди в DM/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці, якщо після появи попереднього перегляду не було надіслано видиме повідомлення, що не є попереднім переглядом - - попередні перегляди, після яких іде видимий вивід, що не є попереднім переглядом: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення та прибирає старіший попередній перегляд, тож фінальна відповідь з’являється після проміжного виводу - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, тож видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди в особистих повідомленнях, групах і темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці, якщо після появи попереднього перегляду не було надіслано видиме повідомлення, яке не є попереднім переглядом + - попередні перегляди, після яких іде видимий вивід, що не є попереднім переглядом: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення й очищає старіший попередній перегляд, тому фінальна відповідь з’являється після проміжного виводу + - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тому видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Потік міркувань лише для Telegram: - - `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерації + - `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерування - попередній перегляд міркувань видаляється після фінальної доставки; використовуйте `/reasoning on`, коли міркування мають залишатися видимими - фінальна відповідь надсилається без тексту міркувань @@ -334,7 +370,7 @@ curl "https://api.telegram.org/bot/getUpdates" Вихідний текст використовує Telegram `parse_mode: "HTML"`. - Текст у стилі Markdown перетворюється на безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram. + - Необроблений HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст. Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені за допомогою `channels.telegram.linkPreview: false`. @@ -342,13 +378,13 @@ curl "https://api.telegram.org/bot/getUpdates" - Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`. + Реєстрація меню команд Telegram обробляється під час запуску за допомогою `setMyCommands`. - Типові значення нативних команд: + Стандартні значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте користувацькі записи меню команд: + Додайте користувацькі пункти меню команд: ```json5 { @@ -365,47 +401,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (видаляється початковий `/`, нижній регістр) + - назви нормалізуються (прибирається початковий `/`, переводяться в нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - користувацькі команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються та записуються в журнал + - конфлікти й дублікати пропускаються та записуються в журнал Примітки: - - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - - команди plugin/skill можуть працювати під час введення, навіть якщо їх не показано в меню Telegram + - користувацькі команди є лише пунктами меню; вони не реалізують поведінку автоматично + - команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди plugin усе ще можуть реєструватися, якщо їх налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди або команди plugin усе ще можуть реєструватися, якщо налаштовані. Поширені збої налаштування: - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` прибирає випадковий кінцевий `/bot`. - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як збій очищення webhook. - - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. + - `setMyCommands failed` з помилками мережі або fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. - ### Команди сполучення пристрою (plugin `device-pair`) + ### Команди спарювання пристроїв (`device-pair` plugin) - Коли plugin `device-pair` установлено: + Коли встановлено `device-pair` plugin: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями) + 3. `/pair pending` показує запити, що очікують на розгляд (зокрема роль/області дії) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один очікуваний запит + - `/pair approve`, коли є лише один запит в очікуванні - `/pair approve latest` для найновішого - Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-областей мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є операторськими, усе ще потрібні області під їхнім власним префіксом ролі. + Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора лишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; неоператорські ролі все ще потребують областей дії під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. + Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області дії/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. - Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). + Докладніше: [Спарювання](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - - Налаштуйте область дії вбудованої клавіатури: + + Налаштуйте область дії inline-клавіатури: ```json5 { @@ -437,7 +473,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Області: + Області дії: - `off` - `dm` @@ -445,7 +481,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` відповідає `inlineButtons: "all"`. Приклад дії повідомлення: @@ -473,11 +509,11 @@ curl "https://api.telegram.org/bot/getUpdates" Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). @@ -488,17 +524,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` зараз увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного розв’язання SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ситуативне повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги гілок відповідей у згенерованому виводі: + + Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск + - `[[reply_to_current]]` відповідає на повідомлення, яке запустило обробку - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -507,29 +543,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли гілки відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли потоки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні гілки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. + Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. - - Супергрупи форуму: + + Супергрупи форумів: - - ключі сесій тем додають `:topic:` - - відповіді та індикація набору спрямовуються в гілку теми + - ключі сесій теми додають `:topic:` + - відповіді й індикатор набору спрямовуються в потік теми - шлях конфігурації теми: `channels.telegram.groups..topics.` Особливий випадок загальної теми (`threadId=1`): - - надсилання повідомлень опускають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії набору тексту все одно включають `message_thread_id` + - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії набору тексту все ще включають `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` є лише тематичним і не успадковується з типових значень групи. + Успадкування теми: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` стосується лише теми й не успадковується зі стандартних значень групи. - **Маршрутизація агента за темою**: кожна тема може спрямовуватися до іншого агента через установлення `agentId` у конфігурації теми. Це дає кожній темі власну ізольовану робочу область, пам’ять і сесію. Приклад: + **Маршрутизація агентів для окремих тем**: кожна тема може спрямовуватися до іншого агента, якщо встановити `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -551,11 +587,11 @@ curl "https://api.telegram.org/bot/getUpdates" Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором з уточненням теми, наприклад `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з уточненням теми, наприклад `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Породження ACP, прив’язане до гілки, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження породження в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). + **Запуск ACP, прив’язаний до потоку, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення спрямовуються безпосередньо туди. OpenClaw закріплює підтвердження запуску в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` лишався ввімкненим (за замовчуванням: `true`). - Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді у пласких сесіях; вони використовують ключі сесій з урахуванням гілок лише тоді, коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня для типового значення облікового запису або `direct..threadReplies` для одного DM. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді в плоских сесіях; вони використовують ключі сесій з урахуванням тредів лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте верхньорівневий `channels.telegram.dm.threadReplies` як типове значення для облікового запису або `direct..threadReplies` для одного DM. @@ -564,10 +600,10 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram розрізняє голосові нотатки та аудіофайли. - - за замовчуванням: поведінка аудіофайлу + - типово: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований, - недовірений текст; виявлення згадок усе ще використовує сирий + - вхідні транскрипти голосових нотаток оформлюються як машинно згенерований, + недовірений текст у контексті агента; виявлення згадок усе ще використовує сирий транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. Приклад дії повідомлення: @@ -604,7 +640,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (заповнювач ``) + - статичний WEBP: завантажується та обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -620,7 +656,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів зору. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору. Увімкнути дії зі стікерами: @@ -661,9 +697,9 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлення). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). - Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт: + Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -674,40 +710,40 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за можливості через кеш надісланих повідомлень). + - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (на основі кешу надісланих повідомлень із найкращим можливим зусиллям). - Події реакцій усе ще дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає ідентифікатори ланцюжків в оновленнях реакцій. - - нефорумні групи спрямовуються до сеансу групового чату - - форумні групи спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми + - Telegram не надає ID тредів в оновленнях реакцій. + - групи не-форуми маршрутизуються до сесії групового чату + - форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для опитування/Webhook автоматично містять `message_reaction`. + `allowed_updates` для polling/Webhook автоматично містить `message_reaction`. - `ackReaction` надсилає emoji-підтвердження, поки OpenClaw обробляє вхідне повідомлення. + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode emoji (наприклад "👀"). + - Telegram очікує unicode-емодзі (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнені типово (`configWrites !== false`). + Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`). Записи, ініційовані Telegram, включають: - - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потрібне ввімкнення команд) + - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` + - `/config set` і `/config unset` (потрібне ввімкнення команди) Вимкнути: @@ -723,30 +759,30 @@ curl "https://api.telegram.org/bot/getUpdates" - - Типово використовується довге опитування. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). + + Типовим є long polling. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло, перш ніж повернути `200` до Telegram. - Потім OpenClaw асинхронно обробляє оновлення через ті самі лінії бота для кожного чату/теми, що використовуються довгим опитуванням, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим Webhook перевіряє захисні умови запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/кожної теми, що використовуються long polling, тож повільні ходи агента не затримують ACK доставки Telegram. - + - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. + - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.mediaGroupFlushMs` (типово 500) контролює, як довго альбоми/медіагрупи Telegram буферизуються, перш ніж OpenClaw відправить їх як одне вхідне повідомлення. Збільште значення, якщо частини альбому надходять пізно; зменште його, щоб скоротити затримку відповіді на альбом. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисту вихідних текстових/typing-запитів, щоб grammY не переривала доставку видимої відповіді до того, як зможуть спрацювати транспортний захист і резервний механізм OpenClaw. Довге опитування все ще використовує 45-секундний захист запиту `getUpdates`, щоб неактивні опитування не залишалися покинутими безстроково. - - Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання опитування. + - `channels.telegram.mediaGroupFlushMs` (типово 500) керує тим, як довго альбоми/медіагрупи Telegram буферизуються, перш ніж OpenClaw відправить їх як одне вхідне повідомлення. Збільште значення, якщо частини альбому надходять із затримкою; зменште його, щоб скоротити затримку відповіді на альбом. + - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисного ліміту для вихідних текстових запитів/typing, щоб grammY не перервав доставку видимої відповіді до того, як зможуть спрацювати транспортний захисний ліміт OpenClaw і fallback. Long polling усе ще використовує 45-секундний захисний ліміт запиту `getUpdates`, щоб неактивні опитування не залишалися покинутими безстроково. + - `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання polling. - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. - - allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - - Контролі історії DM: + - додатковий контекст відповіді/цитати/пересилання наразі передається як отримано. + - Allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної вхідної відповіді також використовує обмежені безпечні повторні спроби надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної відповіді для вхідних повідомлень також використовує обмежений повтор безпечного надсилання для збоїв Telegram перед підключенням, але не повторює неоднозначні мережеві обгортки після надсилання, які можуть дублювати видимі повідомлення. Ціль надсилання CLI може бути числовим ID чату або іменем користувача: @@ -765,7 +801,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Прапорці опитування лише для Telegram: + Прапорці опитувань лише для Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` @@ -774,9 +810,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа + - `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє + - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті + - `--force-document`, щоб надсилати вихідні зображення та GIF-файли як документи замість стислих фото або завантажень анімованих медіа Обмеження дій: @@ -786,36 +822,36 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати підказки в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram. + Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача) - - `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.approvers` (fallback до числових ID власників із `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене парування DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене поєднання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли підказка потрапляє у форумну тему, OpenClaw зберігає тему для підказки схвалення та подальшого повідомлення. Схвалення exec типово закінчуються через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення та подальшої відповіді. Схвалення exec типово спливають через 30 хвилин. - Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення plugin; інші спочатку визначаються через схвалення exec. + Кнопки inline-схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення Plugin; інші спочатку визначаються через схвалення exec. Див. [Схвалення exec](/uk/tools/exec-approvals). -## Контролі відповідей про помилки +## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Два ключі конфігурації керують цією поведінкою: -| Ключ | Значення | Типово | Опис | -| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- | +| Ключ | Значення | Типово | Опис | +| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилками під час збоїв. | +| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для облікового запису, групи й теми (така сама спадковість, як і для інших ключів конфігурації Telegram). +Підтримуються перевизначення для кожного облікового запису, кожної групи та кожної теми (таке саме успадкування, як для інших ключів конфігурації Telegram). ```json5 { @@ -841,51 +877,51 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - потім видаліть і повторно додайте бота до групи - - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадок. + - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - - швидкий тест сеансу: `/activation always`. + - швидкий тест сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути вказана (або має містити `"*"`) + - коли `channels.telegram.groups` існує, групу має бути вказано (або включено `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте ідентичність відправника (парування та/або числовий `allowFrom`) - - авторизація команд усе одно застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість plugin/skill/користувацьких команд або вимкніть нативні меню - - стартові виклики `deleteMyCommands` / `setMyCommands` і typing-виклики `sendChatAction` обмежені та повторюються один раз через транспортний резервний механізм Telegram у разі тайм-ауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми з доступністю DNS/HTTPS до `api.telegram.org` + - авторизуйте ідентичність відправника (сполучення та/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи має значення `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню + - стартові виклики `deleteMyCommands` / `setMyCommands` і виклики введення `sendChatAction` обмежені та повторюються один раз через резервний транспорт Telegram у разі тайм-ауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота. - - Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням. - - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відкладе ту саму помилку неправильного токена до пізніших викликів API. + - Скопіюйте повторно або згенеруйте заново токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. + - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як «webhook не існує» лише відклало б ту саму помилку неправильного токена до пізніших викликів API. - + - - Node 22+ + власний fetch/proxy може спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спочатку розв'язують `api.telegram.org` в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки. - - Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, щоб runner не потребував другого `getMe` перед першим `getUpdates`. - - Якщо `deleteWebhook` завершується тимчасовою мережевою помилкою під час запуску опитування, OpenClaw переходить до long polling замість виконання ще одного керівного виклику перед опитуванням. Webhook, який усе ще активний, проявляється як конфлікт `getUpdates`; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення webhook. - - Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення нижче за захисні межі вихідних запитів і `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці межі. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. - - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис з опитуванням не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис із webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність транспорту опитування застаріла. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`. - - Telegram також враховує env proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще може обходити `api.telegram.org`. - - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й стандартного env proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API. - - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ + користувацький fetch/proxy можуть спричиняти негайну поведінку переривання, якщо типи AbortSignal не збігаються. + - Деякі хости спершу резолвлять `api.telegram.org` в IPv6; зламаний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці запити як відновлювані мережеві помилки. + - Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, тому runner не потребує другого `getMe` перед першим `getUpdates`. + - Якщо `deleteWebhook` завершується тимчасовою мережевою помилкою під час запуску опитування, OpenClaw продовжує long polling замість ще одного передопитувального виклику control-plane. Усе ще активний webhook проявляється як конфлікт `getUpdates`; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення webhook. + - Якщо сокети Telegram перезапускаються з коротким фіксованим інтервалом, перевірте, чи не замале `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення нижче захисних меж вихідних запитів і `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці межі. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної liveness-перевірки long-poll за замовчуванням. + - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис опитування не завершив `getUpdates` після стартового пільгового періоду, коли запущений webhook-обліковий запис не завершив `setWebhook` після стартового пільгового періоду, або коли остання успішна активність транспорту опитування застаріла. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або вихідного TLS-з’єднання між хостом і `api.telegram.org`. + - Telegram також враховує env proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища, а стандартні env proxy відсутні, Telegram також використовує цю URL-адресу для транспорту Bot API. + - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -893,8 +929,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім значення процесу за замовчуванням, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`. - - Якщо ваш хост є WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір family: + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім типове значення процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`. + - Якщо ваш хост — WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -903,10 +939,10 @@ channels: autoSelectFamily: false ``` - - Відповіді діапазону бенчмаркінгу RFC 2544 (`198.18.0.0/15`) уже дозволені - для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або + - Відповіді діапазону для бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені + для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або прозорий proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціальну адресу під час завантаження медіа, ви можете + приватну/внутрішню/спеціальну адресу під час завантажень медіа, ви можете увімкнути обхід лише для Telegram: ```yaml @@ -916,17 +952,17 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Такий самий opt-in доступний для кожного облікового запису за адресою + - Те саме ввімкнення доступне для кожного облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy розв'язує медіахости Telegram у `198.18.x.x`, спочатку залиште + - Якщо ваш proxy резолвить хости медіа Telegram у `198.18.x.x`, спершу залиште небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон - бенчмаркінгу RFC 2544 за замовчуванням. + бенчмарків RFC 2544 за замовчуванням. `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram - media SSRF. Використовуйте це лише для довірених, контрольованих оператором середовищ proxy, - як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони - синтезують приватні чи спеціальні відповіді поза діапазоном бенчмаркінгу + media SSRF. Використовуйте це лише для довірених proxy-середовищ під + контролем оператора, як-от fake-IP-маршрутизація Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціальні відповіді поза діапазоном бенчмарків RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. @@ -944,7 +980,7 @@ dig +short api.telegram.org AAAA -Додаткова допомога: [Усунення неполадок каналів](/uk/channels/troubleshooting). +Додаткова допомога: [Усунення несправностей каналу](/uk/channels/troubleshooting). ## Довідник конфігурації @@ -952,15 +988,15 @@ dig +short api.telegram.org AAAA -- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlink відхиляються) -- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) -- затвердження exec: `execApprovals`, `accounts.*.execApprovals` +- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlinks відхиляються) +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) +- схвалення exec: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` @@ -970,17 +1006,17 @@ dig +short api.telegram.org AAAA -Пріоритетність кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити типову маршрутизацію явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане - - Спаруйте користувача Telegram із gateway. + + Сполучіть користувача Telegram із gateway. - Поведінка allowlist для груп і тем. + Поведінка списку дозволених груп і тем. Маршрутизуйте вхідні повідомлення до агентів. @@ -991,7 +1027,7 @@ dig +short api.telegram.org AAAA Зіставляйте групи й теми з агентами. - - Діагностика між каналами. + + Міжканальна діагностика. diff --git a/docs/uk/concepts/streaming.md b/docs/uk/concepts/streaming.md index 096e20cbf..68924bd29 100644 --- a/docs/uk/concepts/streaming.md +++ b/docs/uk/concepts/streaming.md @@ -1,15 +1,15 @@ --- read_when: - - Пояснення, як у каналах працює потокове передавання або розбиття на фрагменти - - Зміна поведінки потокового передавання блоків або фрагментації каналу - - Налагодження дубльованих або передчасних відповідей блоками чи потокового передавання попереднього перегляду каналу -summary: Поведінка потокового передавання + фрагментації (блокові відповіді, потокове передавання попереднього перегляду каналу, зіставлення режимів) -title: Потокове передавання та розбиття на фрагменти + - Пояснення того, як потокове передавання або розбиття на фрагменти працює в каналах + - Зміна поведінки блокового потокового передавання або фрагментації каналу + - Налагодження дубльованих або передчасних блокових відповідей чи потокового передавання попереднього перегляду каналу +summary: Поведінка потокової передачі + розбиття на фрагменти (блокові відповіді, потокова передача попереднього перегляду каналу, зіставлення режимів) +title: Потокова передача та розбиття на фрагменти x-i18n: - generated_at: "2026-05-04T06:12:39Z" + generated_at: "2026-05-04T07:02:56Z" model: gpt-5.5 provider: openai - source_hash: fcb41ceb5602ab42c3fd41a59de62cc965ea61fdbc058c052fb93689a9c5299b + source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1 source_path: concepts/streaming.md workflow: 16 --- @@ -19,11 +19,11 @@ OpenClaw має два окремі рівні потокового переда - **Блокове потокове передавання (канали):** надсилання завершених **блоків** під час написання відповіді асистентом. Це звичайні повідомлення каналу (не дельти токенів). - **Потокове передавання попереднього перегляду (Telegram/Discord/Slack):** оновлення тимчасового **повідомлення попереднього перегляду** під час генерації. -Наразі **справжнього потокового передавання дельт токенів** у повідомлення каналу немає. Потокове передавання попереднього перегляду базується на повідомленнях (надсилання + редагування/додавання). +Сьогодні **немає справжнього потокового передавання дельт токенів** у повідомлення каналів. Потокове передавання попереднього перегляду працює на рівні повідомлень (надсилання + редагування/додавання). ## Блокове потокове передавання (повідомлення каналу) -Блокове потокове передавання надсилає відповідь асистента великими фрагментами, щойно вони стають доступними. +Блокове потокове передавання надсилає вивід асистента грубими фрагментами, щойно він стає доступним. ``` Model output @@ -37,84 +37,77 @@ Model output Легенда: -- `text_delta/events`: потокові події моделі (можуть бути рідкісними для непотокових моделей). -- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + бажаний тип розриву. +- `text_delta/events`: події потоку моделі (можуть бути розрідженими для непотокових моделей). +- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + перевагу розриву. - `channel send`: фактичні вихідні повідомлення (блокові відповіді). **Елементи керування:** -- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (за замовчуванням вимкнено). +- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (типово вимкнено). - Перевизначення каналів: `*.blockStreaming` (і варіанти для окремих облікових записів), щоб примусово встановити `"on"`/`"off"` для кожного каналу. - `agents.defaults.blockStreamingBreak`: `"text_end"` або `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. - `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднання потокових блоків перед надсиланням). - Жорстке обмеження каналу: `*.textChunkLimit` (наприклад, `channels.whatsapp.textChunkLimit`). -- Режим фрагментації каналу: `*.chunkMode` (`length` за замовчуванням, `newline` розбиває за порожніми рядками (межами абзаців) перед фрагментацією за довжиною). -- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (за замовчуванням 17) розбиває високі відповіді, щоб уникнути обрізання в UI. +- Режим фрагментації каналу: `*.chunkMode` (`length` типово, `newline` розділяє за порожніми рядками (межами абзаців) перед фрагментацією за довжиною). +- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (типово 17) розділяє високі відповіді, щоб уникнути обрізання в інтерфейсі. **Семантика меж:** -- `text_end`: передавати блоки потоком, щойно `chunker` їх випускає; скидати буфер на кожному `text_end`. +- `text_end`: передавати блоки, щойно chunker їх видає; скидати буфер на кожному `text_end`. - `message_end`: чекати завершення повідомлення асистента, потім скидати буферизований вивід. -`message_end` усе одно використовує `chunker`, якщо буферизований текст перевищує `maxChars`, тому наприкінці може бути випущено кілька фрагментів. +`message_end` все одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому наприкінці він може видати кілька фрагментів. ### Доставка медіа з блоковим потоковим передаванням -Директиви `MEDIA:` є звичайними метаданими доставки. Коли блокове потокове передавання рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне навантаження асистента повторює той самий URL медіа, фінальна доставка прибирає дубльоване медіа замість повторного надсилання вкладення. +Директиви `MEDIA:` є звичайними метаданими доставки. Коли блокове потокове передавання рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне корисне навантаження асистента повторює ту саму URL-адресу медіа, фінальна доставка прибирає дубльоване медіа замість повторного надсилання вкладення. -Точні дублікати фінальних навантажень пригнічуються. Якщо фінальне навантаження додає окремий текст навколо медіа, яке вже було передано потоком, OpenClaw усе одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових нотаток або файлів у каналах на кшталт Telegram, коли агент випускає `MEDIA:` під час потокового передавання, а провайдер також включає його в завершену відповідь. +Точні дублікати фінального корисного навантаження пригнічуються. Якщо фінальне корисне навантаження додає окремий текст навколо медіа, яке вже було передано потоково, OpenClaw усе одно надсилає новий текст, зберігаючи медіа як одноразову доставку. Це запобігає дублюванню голосових нотаток або файлів у каналах на кшталт Telegram, коли агент видає `MEDIA:` під час потокового передавання, а провайдер також додає його до завершеної відповіді. -## Алгоритм фрагментації (нижня/верхня межі) +## Алгоритм фрагментації (нижні/верхні межі) -Блокову фрагментацію реалізує `EmbeddedBlockChunker`: +Блокова фрагментація реалізована через `EmbeddedBlockChunker`: -- **Нижня межа:** не випускати, доки буфер >= `minChars` (якщо не примусово). -- **Верхня межа:** віддавати перевагу розбиттю перед `maxChars`; якщо примусово, розбивати на `maxChars`. -- **Бажаний тип розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. -- **Кодові блоки:** ніколи не розбивати всередині блоків; під час примусового розбиття на `maxChars` закривати + повторно відкривати блок, щоб Markdown лишався коректним. +- **Нижня межа:** не видавати, доки буфер >= `minChars` (якщо не примусово). +- **Верхня межа:** віддавати перевагу розділенню до `maxChars`; якщо примусово, розділяти на `maxChars`. +- **Перевага розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. +- **Кодові блоки:** ніколи не розділяти всередині блоків; під час примусового розриву на `maxChars` закривати + знову відкривати блок, щоб Markdown залишався валідним. -`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити обмеження конкретного каналу неможливо. +`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити ліміти окремого каналу неможливо. -## Об’єднання (злиття потокових блоків) +## Коалесценція (об’єднання потокових блоків) -Коли блокове потокове передавання ввімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** -перед їх надсиланням. Це зменшує «спам одним рядком», але все ще забезпечує -поступовий вивід. +Коли блокове потокове передавання ввімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їхнім надсиланням. Це зменшує “спам одним рядком”, водночас зберігаючи поступовий вивід. -- Об’єднання чекає на **паузи простою** (`idleMs`) перед скиданням. -- Буфери обмежуються `maxChars` і скидаються, якщо перевищують це значення. -- `minChars` не дає надсилати крихітні фрагменти, доки не накопичиться достатньо тексту - (фінальне скидання завжди надсилає залишковий текст). -- Розділювач виводиться з `blockStreamingChunk.breakPreference` +- Коалесценція чекає на **паузи бездіяльності** (`idleMs`) перед скиданням буфера. +- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать його. +- `minChars` не дає надсилати крихітні фрагменти, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишок тексту). +- З’єднувач визначається з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл). - Перевизначення каналів доступні через `*.blockStreamingCoalesce` (включно з конфігураціями для окремих облікових записів). -- Стандартне значення `minChars` для об’єднання підвищується до 1500 для Signal/Slack/Discord, якщо його не перевизначено. +- Типове значення коалесценції `minChars` підвищено до 1500 для Signal/Slack/Discord, якщо його не перевизначено. -## Людиноподібний темп між блоками +## Людський темп між блоками -Коли блокове потокове передавання ввімкнено, можна додати **рандомізовану паузу** між -блоковими відповідями (після першого блоку). Це робить відповіді з кількох бульбашок -природнішими. +Коли блокове потокове передавання ввімкнено, можна додати **випадкову паузу** між блоковими відповідями (після першого блока). Це робить відповіді з кількох повідомлень природнішими. -- Конфігурація: `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`). - Застосовується лише до **блокових відповідей**, а не до фінальних відповідей чи підсумків інструментів. -## "Передавати фрагменти потоком або все" +## "Передавати фрагменти чи все" -Це відповідає такому: +Це відповідає: -- **Передавати фрагменти потоком:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (випускати поступово). Канали не-Telegram також потребують `*.blockStreaming: true`. -- **Передавати все потоком наприкінці:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо кількома фрагментами, якщо дуже довго). +- **Передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (видавати в процесі). Каналам, крім Telegram, також потрібен `*.blockStreaming: true`. +- **Передавати все наприкінці:** `blockStreamingBreak: "message_end"` (одноразове скидання, можливо кількома фрагментами, якщо дуже довго). - **Без блокового потокового передавання:** `blockStreamingDefault: "off"` (лише фінальна відповідь). -**Примітка щодо каналів:** Блокове потокове передавання **вимкнене, якщо** -`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд -(`channels..streaming`) без блокових відповідей. +**Примітка щодо каналів:** блокове потокове передавання **вимкнено, якщо** +`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд (`channels..streaming`) без блокових відповідей. -Нагадування про розташування конфігурації: стандартні значення `blockStreaming*` містяться в -`agents.defaults`, а не в кореневій конфігурації. +Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в кореневій конфігурації. ## Режими потокового передавання попереднього перегляду @@ -125,86 +118,81 @@ Model output - `off`: вимкнути потокове передавання попереднього перегляду. - `partial`: один попередній перегляд, який замінюється найновішим текстом. - `block`: попередній перегляд оновлюється фрагментованими/доданими кроками. -- `progress`: попередній перегляд прогресу/статусу під час генерації, фінальна відповідь після завершення. +- `progress`: попередній перегляд прогресу/стану під час генерації, фінальна відповідь після завершення. -`streaming.mode: "block"` — це режим потокового передавання попереднього перегляду для каналів -з підтримкою редагування, як-от Discord і Telegram. Він не вмикає там блокову доставку каналу. -Використовуйте `streaming.block.enabled` або застарілий ключ каналу `blockStreaming`, коли -потрібні звичайні блокові відповіді. Microsoft Teams є винятком: у нього немає -транспорту чернеток-попередніх переглядів для блоків, тому `streaming.mode: "block"` у Teams відповідає -блоковій доставці замість нативного часткового/прогресивного потокового передавання. +`streaming.mode: "block"` — це режим потокового передавання попереднього перегляду для каналів із можливістю редагування, таких як Discord і Telegram. Він не вмикає там доставку блоків каналу. Використовуйте `streaming.block.enabled` або застарілий ключ каналу `blockStreaming`, коли потрібні звичайні блокові відповіді. Microsoft Teams — виняток: там немає транспорту блоків чорнового попереднього перегляду, тому `streaming.mode: "block"` зіставляється з доставкою блоків Teams, а не з нативним частковим/прогресовим потоковим передаванням. -### Відповідність каналів +### Зіставлення каналів -| Канал | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | -------------------------- | -| Telegram | ✅ | ✅ | ✅ | редагована чернетка прогресу | -| Discord | ✅ | ✅ | ✅ | редагована чернетка прогресу | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | -| MS Teams | ✅ | ✅ | ✅ | нативний потік прогресу | +| Канал | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ----------------------- | +| Telegram | ✅ | ✅ | ✅ | редагований чорновик прогресу | +| Discord | ✅ | ✅ | ✅ | редагований чорновик прогресу | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | +| MS Teams | ✅ | ✅ | ✅ | нативний потік прогресу | Лише Slack: -- `channels.slack.streaming.nativeTransport` перемикає виклики нативного API потокового передавання Slack, коли `channels.slack.streaming.mode="partial"` (за замовчуванням: `true`). -- Нативне потокове передавання Slack і статус гілки асистента Slack потребують цільової гілки відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі гілки, але все одно можуть використовувати дописи чернеток попереднього перегляду Slack і редагування. +- `channels.slack.streaming.nativeTransport` перемикає нативні виклики API потокового передавання Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`). +- Нативне потокове передавання Slack і статус потоку асистента Slack потребують цільового потоку відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі потоку, але все одно можуть використовувати чорнові публікації попереднього перегляду Slack і редагування. Міграція застарілих ключів: - Telegram: застарілі значення `streamMode` і скалярні/булеві значення `streaming` виявляються та мігруються шляхами сумісності doctor/config до `streaming.mode`. -- Discord: `streamMode` + булевий `streaming` автоматично мігрують до enum `streaming`. +- Discord: `streamMode` + булевий `streaming` автоматично мігрують до переліку `streaming`. - Slack: `streamMode` автоматично мігрує до `streaming.mode`; булевий `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`. ### Поведінка під час виконання Telegram: -- Використовує `sendMessage` + `editMessageText` для оновлень попереднього перегляду в DM, групах і темах. -- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий приблизно одну хвилину, а потім прибирає попередній перегляд, щоб мітка часу Telegram відображала завершення відповіді. -- Потокове передавання попереднього перегляду пропускається, коли блокове потокове передавання Telegram явно ввімкнене (щоб уникнути подвійного потокового передавання). -- `/reasoning stream` може записувати міркування в тимчасовий попередній перегляд, який видаляється після фінальної доставки. +- Використовує `sendMessage` + `editMessageText` для оновлень попереднього перегляду в DM і групах/темах. +- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий близько однієї хвилини, потім очищає попередній перегляд, щоб часова мітка Telegram відображала завершення відповіді. +- Потокове передавання попереднього перегляду пропускається, коли блокове потокове передавання Telegram явно ввімкнено (щоб уникнути подвійного потокового передавання). +- `/reasoning stream` може записувати reasoning до тимчасового попереднього перегляду, який видаляється після фінальної доставки. Discord: - Використовує надсилання + редагування повідомлень попереднього перегляду. -- Режим `block` використовує фрагментацію чернетки (`draftChunk`). -- Потокове передавання попереднього перегляду пропускається, коли блокове потокове передавання Discord явно ввімкнене. -- Фінальні медіа, помилки й навантаження явних відповідей скасовують очікувані попередні перегляди без скидання нової чернетки, а потім використовують звичайну доставку. +- Режим `block` використовує фрагментацію чорновика (`draftChunk`). +- Потокове передавання попереднього перегляду пропускається, коли блокове потокове передавання Discord явно ввімкнено. +- Фінальні медіа, помилки й корисні навантаження явної відповіді скасовують очікувані попередні перегляди без скидання нового чорновика, а потім використовують звичайну доставку. Slack: - `partial` може використовувати нативне потокове передавання Slack (`chat.startStream`/`append`/`stop`), коли воно доступне. -- `block` використовує чернетки попереднього перегляду в стилі додавання. -- `progress` використовує текст попереднього перегляду статусу, а потім фінальну відповідь. -- DM верхнього рівня без гілки відповіді використовують дописи чернеток попереднього перегляду та редагування замість нативного потокового передавання Slack. -- Нативне й чернеткове потокове передавання попереднього перегляду пригнічує блокові відповіді для цього ходу, тому відповідь Slack передається лише одним шляхом доставки. -- Фінальні навантаження медіа/помилок і фінали прогресу не створюють одноразових чернеток повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний текст чернетки. +- `block` використовує чорнові попередні перегляди в стилі додавання. +- `progress` використовує текст попереднього перегляду стану, потім фінальну відповідь. +- DM верхнього рівня без потоку відповіді використовують чорнові публікації попереднього перегляду та редагування замість нативного потокового передавання Slack. +- Нативне й чорнове потокове передавання попереднього перегляду пригнічує блокові відповіді для цього ходу, тому відповідь Slack передається лише одним шляхом доставки. +- Фінальні корисні навантаження медіа/помилок і фінали прогресу не створюють одноразових чорнових повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний чорновий текст. Mattermost: -- Передає думки, активність інструментів і частковий текст відповіді в один допис чернетки попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надіслати. -- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний під час фіналізації. -- Фінальні навантаження медіа/помилок скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасового допису попереднього перегляду. +- Передає мислення, активність інструментів і частковий текст відповіді в одну чорнову публікацію попереднього перегляду, яка фіналізується на місці, коли фінальну відповідь безпечно надіслати. +- Повертається до надсилання нової фінальної публікації, якщо публікацію попереднього перегляду було видалено або вона інакше недоступна під час фіналізації. +- Фінальні корисні навантаження медіа/помилок скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасової публікації попереднього перегляду. Matrix: -- Чернетки попереднього перегляду фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. -- Фінали лише з медіа, помилками та невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується. +- Чорнові попередні перегляди фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. +- Фінали лише з медіа, помилками або невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; вже видимий застарілий попередній перегляд редагується. ### Оновлення попереднього перегляду прогресу інструментів -Потокове передавання попереднього перегляду також може включати оновлення **прогресу інструментів** — короткі рядки статусу на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента", — які з’являються в тому самому повідомленні попереднього перегляду, поки інструменти працюють, перед фінальною відповіддю. Це робить багатоетапні ходи з інструментами візуально активними, а не тихими між першим попереднім переглядом думок і фінальною відповіддю. +Потокове передавання попереднього перегляду також може містити оновлення **прогресу інструментів** — короткі рядки стану на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента" — які з’являються в тому самому повідомленні попереднього перегляду, поки інструменти виконуються, перед фінальною відповіддю. Це зберігає візуальну активність багатоетапних ходів з інструментами, а не залишає тишу між першим попереднім переглядом мислення та фінальною відповіддю. Підтримувані поверхні: -- **Discord**, **Slack**, **Telegram** і **Matrix** за замовчуванням передають прогрес інструментів у редагування живого попереднього перегляду, коли потокове передавання попереднього перегляду активне. Microsoft Teams використовує свій нативний потік прогресу в особистих чатах. -- Telegram постачається з увімкненими оновленнями попереднього перегляду прогресу інструментів із `v2026.4.22`; збереження їх увімкненими підтримує цю випущену поведінку. -- **Mattermost** уже вкладає активність інструментів у свій єдиний допис чернетки попереднього перегляду (див. вище). -- Редагування прогресу інструментів дотримуються активного режиму потокового передавання попереднього перегляду; вони пропускаються, коли потокове передавання попереднього перегляду має значення `off` або коли блокове потокове передавання перебрало повідомлення. У Telegram `streaming.mode: "off"` означає лише фінал: загальні повідомлення про прогрес також пригнічуються замість доставки як окремі статусні повідомлення, тоді як запити на схвалення, медіанавантаження й помилки все одно маршрутизуються звичайно. -- Щоб зберегти потокове передавання попереднього перегляду, але приховати рядки прогресу інструментів, установіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, установіть `streaming.mode` у `off`. -- Відповіді Telegram із вибраною цитатою є винятком: коли `replyToMode` не дорівнює `"off"` і є текст вибраної цитати, OpenClaw пропускає потік попереднього перегляду відповіді для цього ходу, тому рядки попереднього перегляду прогресу інструментів не можуть відобразитися. Відповіді на поточне повідомлення без тексту вибраної цитати все ще зберігають потокове передавання попереднього перегляду. Докладніше див. у [документації каналу Telegram](/uk/channels/telegram). +- **Discord**, **Slack**, **Telegram** і **Matrix** типово передають прогрес інструментів у редагування живого попереднього перегляду, коли потокове передавання попереднього перегляду активне. Microsoft Teams використовує нативний потік прогресу в особистих чатах. +- Telegram постачається з увімкненими оновленнями попереднього перегляду прогресу інструментів починаючи з `v2026.4.22`; їхнє ввімкнення зберігає випущену поведінку. +- **Mattermost** уже включає активність інструментів у свою єдину чорнову публікацію попереднього перегляду (див. вище). +- Редагування прогресу інструментів відповідають активному режиму потокового передавання попереднього перегляду; вони пропускаються, коли потокове передавання попереднього перегляду має значення `off` або коли блокове потокове передавання перебрало на себе повідомлення. У Telegram `streaming.mode: "off"` означає лише фінальну відповідь: загальні повідомлення про прогрес також пригнічуються замість доставки як окремі повідомлення стану, тоді як запити на схвалення, медіакорисні навантаження та помилки все одно маршрутизуються звичайно. +- Щоб зберегти потокове передавання попереднього перегляду, але приховати рядки прогресу інструментів, установіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб рядки прогресу інструментів залишалися видимими, але текст команд/виконання був прихований, установіть `streaming.preview.commandText` у `"status"` або `streaming.progress.commandText` у `"status"`; типове значення — `"raw"`, щоб зберегти випущену поведінку. Ця політика спільна для чорнових/прогресових каналів, які використовують компактний рендерер прогресу OpenClaw, зокрема Discord, Matrix, Microsoft Teams, Mattermost, чорнових попередніх переглядів Slack і Telegram. Щоб повністю вимкнути редагування попереднього перегляду, установіть `streaming.mode` у `off`. +- Вибрані цитовані відповіді Telegram є винятком: коли `replyToMode` не дорівнює `"off"` і присутній вибраний текст цитати, OpenClaw пропускає потік попереднього перегляду відповіді для цього ходу, тому рядки попереднього перегляду прогресу інструментів не можуть відобразитися. Відповіді на поточне повідомлення без вибраного тексту цитати все одно зберігають потокове передавання попереднього перегляду. Докладніше див. у [документації каналу Telegram](/uk/channels/telegram). -Приклад: +Показуйте рядки прогресу, але приховуйте необроблений текст команди/виконання: ```json { @@ -213,7 +201,26 @@ Matrix: "streaming": { "mode": "partial", "preview": { - "toolProgress": false + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` + +Використовуйте ту саму форму під іншим ключем компактного каналу прогресу, наприклад `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost` або попередніми переглядами чернеток Slack. Для режиму чернеток прогресу розмістіть ту саму політику під `streaming.progress`: + +```json +{ + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" } } } @@ -223,7 +230,7 @@ Matrix: ## Пов’язане -- [Чернетки прогресу](/uk/concepts/progress-drafts) — видимі повідомлення про поточну роботу, які оновлюються під час тривалих ходів +- [Чернетки прогресу](/uk/concepts/progress-drafts) — видимі повідомлення про роботу в процесі, які оновлюються під час довгих ходів - [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлень і доставка -- [Повторна спроба](/uk/concepts/retry) — поведінка повторних спроб у разі збою доставки +- [Повторна спроба](/uk/concepts/retry) — поведінка повторних спроб у разі помилки доставки - [Канали](/uk/channels) — підтримка потокового передавання для кожного каналу