diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 00b492dc9..32a0a291f 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,28 +1,28 @@ --- read_when: - - Робота над функціями Telegram або Webhook-ами -summary: Статус підтримки, можливості та конфігурація бота Telegram + - Робота над функціями Telegram або Webhook +summary: Статус підтримки бота Telegram, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-04-26T05:36:20Z" + generated_at: "2026-04-26T22:47:42Z" model: gpt-5.4 provider: openai - source_hash: b7d269b15bc2d377fa45f0516e435517ed366c0216d0bc31fe4f4bc080a6c726 + source_hash: be2af133453fa0cce99c6137077206a0f83d95a62594bf6d8e25d94d1b9c56cd source_path: channels/telegram.md workflow: 15 --- -Готовий до продакшн-використання для DM бота та груп через grammY. Long polling — режим за замовчуванням; режим Webhook — необов’язковий. +Готово до продакшну для DM бота та груп через grammY. Довге опитування — типовий режим; режим Webhook — необов’язковий. - - Типова політика DM для Telegram — зв’язування. + + Типова політика DM для Telegram — сполучення. Міжканальна діагностика та сценарії відновлення. - Повні шаблони й приклади конфігурації каналів. + Повні шаблони та приклади конфігурації каналів. @@ -30,7 +30,7 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що хендл точно `@BotFather`). + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я користувача точно `@BotFather`). Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. @@ -51,7 +51,7 @@ x-i18n: } ``` - Резервне значення через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням). + Резервне значення через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише для типового облікового запису). Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. @@ -64,7 +64,7 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди зв’язування дійсні протягом 1 години. + Коди сполучення дійсні протягом 1 години. @@ -74,21 +74,21 @@ openclaw pairing approve telegram -Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням з env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням із змінної середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису. -## Налаштування з боку Telegram +## Налаштування на боці Telegram - - За замовчуванням боти Telegram працюють у **Privacy Mode**, що обмежує, які повідомлення в групах вони отримують. + + Для ботів Telegram типовим є **Privacy Mode**, який обмежує, які повідомлення в групах вони отримують. Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого: - - вимкніть режим конфіденційності через `/setprivacy`, або + - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після зміни режиму конфіденційності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну. @@ -102,7 +102,7 @@ openclaw pairing approve telegram - `/setjoingroups` — дозволити/заборонити додавання до груп - - `/setprivacy` — поведінка видимості в групах + - `/setprivacy` — керування видимістю в групах @@ -113,64 +113,64 @@ openclaw pairing approve telegram `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - - `pairing` (за замовчуванням) + - `pairing` (типово) - `allowlist` (потрібен щонайменше один ID відправника в `allowFrom`) - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` - `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. - `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config. - Під час налаштування запитуються лише числові ID користувачів. - Якщо ви оновилися й ваша config містить записи allowlist у вигляді `@username`, виконайте `openclaw doctor --fix`, щоб перетворити їх (best-effort; потрібен токен бота Telegram). - Якщо ви раніше покладалися на файли allowlist у pairing-store, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для сценаріїв allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` підтримуються та нормалізуються. + `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється під час валідації конфігурації. + Налаштування запитує лише числові ID користувачів. + Якщо ви оновилися і ваша конфігурація містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб їх виправити (best-effort; потрібен токен бота Telegram). + Якщо ви раніше покладалися на файли allowlist зі сховища pairing-store, `openclaw doctor --fix` може відновити записи до `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів із одним власником надавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень зв’язування). + Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалась у конфігурації (а не залежала від попередніх схвалень сполучення). - Поширена плутанина: схвалення зв’язування DM не означає, що «цей відправник авторизований усюди». - Зв’язування надає доступ лише до DM. Авторизація відправника в групах усе ще визначається явними allowlist у config. - Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`. + Поширена плутанина: схвалення сполучення для DM не означає, що «цей відправник авторизований усюди». + Сполучення надає доступ лише до DM. Авторизація відправників у групах, як і раніше, походить з явних allowlist у конфігурації. + Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`. ### Як знайти свій ID користувача Telegram Безпечніший спосіб (без стороннього бота): - 1. Надішліть DM своєму боту. + 1. Напишіть своєму боту в DM. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. - Офіційний метод через Bot API: + Офіційний спосіб через Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` - Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`. + Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`. - Разом застосовуються два елементи керування: + Разом застосовуються два механізми керування: 1. **Які групи дозволені** (`channels.telegram.groups`) - - немає config `groups`: + - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - - з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`) + - з `groupPolicy: "allowlist"` (типово): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`) - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - - `allowlist` (за замовчуванням) + - `allowlist` (типово) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує резервне значення з `allowFrom`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram використовує резервне значення з `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються). - Не додавайте ID чатів Telegram group або supergroup у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення DM із pairing-store. - Зв’язування залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми. - Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з config `allowFrom`, а не pairing store. - Практичний шаблон для ботів із одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в режимі fail-closed з `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно. + Не вказуйте ID груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`. + Нечислові записи ігноруються під час авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища pairing-store для DM. + Сполучення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для конкретної групи/теми. + Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з `allowFrom` у конфігурації, а не зі сховища pairing-store. + Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте потрібні групи через `channels.telegram.groups`. + Примітка щодо виконання: якщо `channels.telegram` повністю відсутній, під час виконання типовим буде fail-closed `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -209,31 +209,31 @@ curl "https://api.telegram.org/bot/getUpdates" Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram. - - Додавайте від’ємні ID Telegram group або supergroup, як-от `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. + - Розміщуйте від’ємні ID груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Розміщуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, якщо хочете обмежити, які люди всередині дозволеної групи можуть викликати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише коли хочете, щоб будь-який учасник дозволеної групи міг звертатися до бота. - - Відповіді в групах за замовчуванням вимагають згадки. + + У групах відповіді типово потребують згадування. - Згадка може надходити з: + Згадування може надходити з: - нативної згадки `@botusername`, або - - шаблонів згадки в: + - шаблонів згадування в: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд на рівні сесії: + Перемикачі команд рівня сесії: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для збереження використовуйте config. + Вони оновлюють лише стан сесії. Для постійного збереження використовуйте конфігурацію. - Приклад сталої config: + Приклад постійної конфігурації: ```json5 { @@ -247,44 +247,44 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Отримання ID групового чату: + Як отримати ID групового чату: - перешліть повідомлення з групи до `@userinfobot` / `@getidsbot` - - або прочитайте `chat.id` з `openclaw logs --follow` - - або перевірте Bot API `getUpdates` + - або прочитайте `chat.id` у `openclaw logs --follow` + - або перегляньте Bot API `getUpdates` -## Поведінка runtime +## Поведінка під час виконання - Telegram належить процесу gateway. - Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали). - Вхідні повідомлення нормалізуються до спільного конверта каналу з метаданими відповіді та заповнювачами медіа. -- Сесії груп ізольовані за ID групи. Для forum topics додається `:topic:`, щоб ізолювати теми. -- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії, що враховують thread, і зберігає ID thread для відповідей. -- Long polling використовує grammY runner із послідовною обробкою для кожного чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`. -- Long polling захищений у межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller. -- Перезапуски watchdog для long polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні й далі виникають хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і може бути від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Сесії груп ізольовані за ID групи. Теми форуму додають `:topic:`, щоб ізолювати теми. +- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх за допомогою ключів сесії з урахуванням потоку та зберігає ID потоку для відповідей. +- Довге опитування використовує grammY runner з послідовністю на рівні чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене в межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller. +- Перезапуски watchdog для довгого опитування типово спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs`, лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. - Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). -## Довідник можливостей +## Довідник функцій - - OpenClaw може транслювати часткові відповіді в реальному часі: + + OpenClaw може передавати часткові відповіді в реальному часі: - прямі чати: повідомлення попереднього перегляду + `editMessageText` - групи/теми: повідомлення попереднього перегляду + `editMessageText` Вимога: - - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) + - `channels.telegram.streaming` має значення `off | partial | block | progress` (типово: `partial`) - `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення tool/progress повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активне preview streaming) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` + - `streaming.preview.toolProgress` визначає, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (типово: `true`, коли активний попередній перегляд потоку) + - застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` визначаються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` - Оновлення попереднього перегляду tool-progress — це короткі рядки «Працюю...», які показуються під час виконання інструментів, наприклад під час виконання команд, читання файлів, оновлень планування або зведень патчів. У Telegram вони увімкнені за замовчуванням, щоб відповідати випущеній поведінці OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки tool-progress, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Working...», що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень плану або підсумків патчів. У Telegram вони типово ввімкнені, щоб відповідати поведінці випущених версій OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -301,45 +301,45 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки статусу tool-progress. + Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів. Для відповідей лише з текстом: - - DM: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення) - - group/topic: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення) + - короткі попередні перегляди в DM/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, щоб видимий часовий штамп у Telegram відображав час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, з медіавмістом) OpenClaw використовує резервну звичайну фінальну доставку, а потім прибирає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, корисних навантажень із медіа) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду. - Preview streaming відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного стримінгу. + Потоковий попередній перегляд відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. - Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично використовує резервний варіант `sendMessage` + `editMessageText`. + Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично переходить на `sendMessage` + `editMessageText`. - Потік reasoning лише для Telegram: + Потік міркування лише для Telegram: - - `/reasoning stream` надсилає reasoning у live preview під час генерації - - фінальна відповідь надсилається без тексту reasoning + - `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерації + - фінальна відповідь надсилається без тексту міркування - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Текст у стилі Markdown відтворюється як HTML, безпечний для Telegram. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram. + - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. + - Необроблений HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. - Попередній перегляд посилань увімкнений за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`. + Попередній перегляд посилань увімкнено типово; його можна вимкнути за допомогою `channels.telegram.linkPreview: false`. - Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`. + Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Типові налаштування нативних команд: + Типові значення для нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте власні пункти меню команд: + Додайте користувацькі записи до меню команд: ```json5 { @@ -356,40 +356,40 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) + - імена нормалізуються (прибирається початковий `/`, перетворюються на нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - користувацькі команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються та записуються в журнал + - конфлікти/дублікати пропускаються та журналюються Примітки: - - користувацькі команди — це лише пункти меню; вони не реалізують поведінку автоматично - - команди Plugin/Skills все одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram + - користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично + - команди Plugin/Skills можуть і далі працювати під час ручного введення, навіть якщо вони не показані в меню Telegram - Якщо нативні команди вимкнені, вбудовані команди видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть і далі реєструватися, якщо це налаштовано. - Поширені збої налаштування: + Поширені помилки налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене навіть після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблокований. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене після скорочення; зменште кількість користувацьких команд/команд Plugin/Skills або вимкніть `channels.telegram.commands.native`. + - `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані. - ### Команди зв’язування пристрою (`device-pair` Plugin) + ### Команди сполучення пристроїв (Plugin `device-pair`) Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список очікуваних запитів (включно з роллю/scopes) + 3. `/pair pending` показує список незавершених запитів (включно з роллю/scopes) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один очікуваний запит + - `/pair approve`, коли є лише один незавершений запит - `/pair approve latest` для найновішого - Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен первинного Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролям, що не є оператором, усе ще потрібні scopes під префіксом їхньої власної ролі. + Код налаштування містить короткочасний bootstrap token. Вбудована передача bootstrap зберігає токен основного Node на `scopes: []`; будь-який переданий operator token залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope використовують префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є оператором, як і раніше потрібні scopes під власним префіксом ролі. - Якщо пристрій повторно надсилає запит зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. + Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/scopes/public key), попередній незавершений запит замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. - Докладніше: [Зв’язування](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). + Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -432,7 +432,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `dm` - `group` - `all` - - `allowlist` (за замовчуванням) + - `allowlist` (типово) Застаріле `capabilities: ["inlineButtons"]` відповідає `inlineButtons: "all"`. @@ -443,7 +443,7 @@ curl "https://api.telegram.org/bot/getUpdates" action: "send", channel: "telegram", to: "123456789", - message: "Оберіть варіант:", + message: "Виберіть варіант:", buttons: [ [ { text: "Так", callback_data: "yes" }, @@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Дії інструментів Telegram включають: - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) @@ -470,55 +470,55 @@ curl "https://api.telegram.org/bot/getUpdates" Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Керування обмеженнями: + Керування доступом: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) + - `channels.telegram.actions.sticker` (типово: вимкнено) - Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час runtime використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` наразі типово ввімкнені й не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі: + + Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` — відповідь на повідомлення, що спричинило спрацювання - - `[[reply_to:]]` — відповідь на конкретний ID повідомлення Telegram + - `[[reply_to_current]]` відповідає на повідомлення, що спричинило дію + - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: - - `off` (за замовчуванням) + - `off` (типово) - `first` - `all` - Коли ланцюжки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує текст нативної цитати до 1024 кодових одиниць UTF-16, тому довші повідомлення цитуються з початку й використовують резервний звичайний reply, якщо Telegram відхиляє цитату. + Коли потоки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати до 1024 кодових одиниць UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - - Forum supergroup: + + Супергрупи форуму: - - ключі сесії теми доповнюються `:topic:` - - відповіді й індикація набору тексту спрямовуються в потік теми - - шлях config теми: + - ключі сесій тем додають `:topic:` + - відповіді та індикатор набору спрямовуються в потік теми + - шлях конфігурації теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії індикації набору тексту все одно включають `message_thread_id` + - дії індикатора набору все одно містять `message_thread_id` Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` призначений лише для тем і не успадковується з типових налаштувань групи. + `agentId` призначений лише для тем і не успадковується з типових значень групи. - **Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агента для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -529,7 +529,7 @@ curl "https://api.telegram.org/bot/getUpdates" topics: { "1": { agentId: "main" }, // Загальна тема → основний агент "3": { agentId: "zu" }, // Тема розробки → агент zu - "5": { agentId: "coder" } // Огляд коду → агент coder + "5": { agentId: "coder" } // Перевірка коду → агент coder } } } @@ -538,13 +538,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Тоді кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема тоді має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Стале прив’язування тем ACP**: Forum topics можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми, як-от `-1001234567890:topic:42`). Наразі це обмежено forum topics у groups/supergroups. Див. [ACP Agents](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: Теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми на кшталт `-1001234567890:topic:42`). Наразі це обмежено темами форумів у групах/супергрупах. Див. [ACP Agents](/uk/tools/acp-agents). - **Прив’язаний до потоку запуск ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди безпосередньо. OpenClaw закріплює підтвердження запуску в межах теми. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Запуск ACP із чату з прив’язкою до потоку**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди безпосередньо. OpenClaw закріплює підтвердження запуску в межах теми. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням thread. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням потоку. @@ -553,11 +553,11 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram розрізняє голосові повідомлення та аудіофайли. - - за замовчуванням: поведінка аудіофайлу + - типово: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення - - вхідні транскрипти голосових повідомлень оформлюються в контексті агента як машинно згенерований, - недовірений текст; виявлення згадок усе ще використовує сирий - транскрипт, тож голосові повідомлення з обмеженням за згадкою продовжують працювати. + - транскрипти вхідних голосових повідомлень оформлюються в контексті агента як машинно згенерований, + недовірений текст; виявлення згадувань усе одно використовує сирий + транскрипт, тому голосові повідомлення з обмеженням за згадуванням продовжують працювати. Приклад дії повідомлення: @@ -573,7 +573,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли та video notes. + Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: @@ -587,7 +587,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Video notes не підтримують підписи; наданий текст повідомлення надсилається окремо. + Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо. ### Стікери @@ -609,9 +609,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision. + Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити кількість повторних викликів vision. - Увімкнення дій зі стікерами: + Увімкніть дії зі стікерами: ```json5 { @@ -642,7 +642,7 @@ curl "https://api.telegram.org/bot/getUpdates" { action: "sticker-search", channel: "telegram", - query: "кіт махає", + query: "cat waving", limit: 5, } ``` @@ -650,24 +650,24 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисних навантажень повідомлень). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). - Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт: + Коли цю функцію ввімкнено, OpenClaw ставить у чергу системні події на кшталт: - `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 42` - Config: + Конфігурація: - - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`) Примітки: - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). - - Події реакцій усе ще дотримуються керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Події реакцій усе одно враховують механізми керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - Telegram не надає ID потоку в оновленнях реакцій. - - групи не forum маршрутизуються до сесії групового чату - - forum groups маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - у нефорумних групах маршрутизація йде до сесії групового чату + - у форумних групах маршрутизація йде до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми `allowed_updates` для polling/webhook автоматично включають `message_reaction`. @@ -685,13 +685,13 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - - Telegram очікує емодзі Unicode (наприклад, "👀"). + - Telegram очікує Unicode-емодзі (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - - Записи config каналу увімкнені за замовчуванням (`configWrites !== false`). + + Запис конфігурації каналу типово ввімкнений (`configWrites !== false`). Записи, ініційовані Telegram, включають: @@ -712,38 +712,38 @@ curl "https://api.telegram.org/bot/getUpdates" - - За замовчуванням використовується long polling. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково — `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). + + Типово використовується довге опитування. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові параметри: `webhookPath`, `webhookHost`, `webhookPort` (типові значення: `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захист запитів, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. - Потім OpenClaw асинхронно обробляє оновлення через ті самі бот-черги для кожного чату/теми, що використовуються в long polling, тож повільні цикли агента не затримують ACK доставки Telegram. + У режимі Webhook перед поверненням `200` до Telegram виконується перевірка захисту запиту, секретного токена Telegram і JSON-тіла. + Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота на рівні чату/теми, що й для довгого опитування, тому повільні ходи агента не затримують ACK доставки Telegram. - + - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. - - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. - - Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - Додатковий контекст reply/quote/forward наразі передається в отриманому вигляді. - - Telegram allowlist насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіафайлів Telegram. + - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, використовується типове значення grammY). + - Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання опитування. + - Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає її. + - Додатковий контекст reply/quote/forward наразі передається як отримано. + - Allowlist у Telegram насамперед визначають, хто може викликати агента, а не є повною межею редагування додаткового контексту. - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Config `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. + - Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. - Ціллю надсилання CLI може бути числовий ID чату або ім’я користувача: + Ціль надсилання CLI може бути числовим ID чату або іменем користувача: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Опитування Telegram використовують `openclaw message poll` і підтримують forum topics: + Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -758,50 +758,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для forum topics (або використовуйте ціль `:topic:`) + - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) - Надсилання Telegram також підтримує: + Надсилання в Telegram також підтримує: - - `--presentation` з блоками `buttons` для вбудованих клавіатур, якщо це дозволяє `channels.telegram.capabilities.inlineButtons` - - `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, якщо бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа + - `--presentation` із блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons` + - `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, якщо бот може закріплювати повідомлення в цьому чаті + - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фотографій або завантажень анімованих медіа - Керування обмеженнями дій: + Керування діями: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями - - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання увімкненим + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим - - Telegram підтримує погодження exec у DM погоджувачів і за потреби може публікувати запити в початковому чаті або темі. Погоджувачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує схвалення exec у DM схвалювачів і може додатково публікувати запити в початковому чаті або темі. Схвалювачами мають бути числові ID користувачів Telegram. - Шлях config: + Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного погоджувача) - - `channels.telegram.execApprovals.approvers` (використовує резервне значення з числових owner ID із `allowFrom` / `defaultTo`) - - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного схвалювача) + - `channels.telegram.execApprovals.approvers` (використовує як резервне значення числові ID власників із `allowFrom` / `defaultTo`) + - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` - `agentFilter`, `sessionFilter` - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених groups/topics. Коли запит потрапляє у forum topic, OpenClaw зберігає тему для запиту на погодження та подальших повідомлень. За замовчуванням погодження exec спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на схвалення та подальших повідомлень. Типово схвалення exec закінчуються через 30 хвилин. - Вбудовані кнопки погодження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID погоджень із префіксом `plugin:` визначаються через погодження Plugin; інші спочатку визначаються через погодження exec. + Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення Plugin; інші спочатку визначаються через схвалення exec. - Див. [Погодження exec](/uk/tools/exec-approvals). + Див. [Схвалення exec](/uk/tools/exec-approvals). ## Керування відповідями на помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цією поведінкою керують два ключі config: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації: | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає в чат дружнє повідомлення про помилку. `silent` повністю пригнічує відповіді з помилками. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в одному й тому самому чаті. Запобігає спаму помилками під час збоїв. | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю пригнічує відповіді з помилками. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в одному й тому самому чаті. Запобігає спаму помилок під час збоїв. | -Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів config Telegram). +Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів конфігурації Telegram). ```json5 { @@ -811,7 +811,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ errorCooldownMs: 120000, groups: { "-1001234567890": { - errorPolicy: "silent", // пригнічує помилки в цій групі + errorPolicy: "silent", // пригнічувати помилки в цій групі }, }, }, @@ -822,42 +822,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Усунення проблем - + - - Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість. + - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть бота й додайте його знову до групи - - `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` неможливо перевірити на членство. - - швидкий тест сесії: `/activation always`. + - потім видаліть і знову додайте бота до групи + - `openclaw channels status` попереджає, коли конфігурація очікує повідомлення в групі без згадування. + - `openclaw channels status --probe` може перевіряти явні числові ID груп; членство для шаблону `"*"` перевірити не можна. + - швидка перевірка сесії: `/activation always`. - - коли існує `channels.telegram.groups`, група має бути вказана в списку (або має бути `"*"`) - - перевірте членство бота в групі + - коли існує `channels.telegram.groups`, група має бути в списку (або має бути `"*"`) + - перевірте, що бот є учасником групи - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте свою ідентичність відправника (pairing та/або числовий `allowFrom`) - - авторизація команд усе ще застосовується, навіть коли політика групи `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню занадто багато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню - - `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми з досяжністю DNS/HTTPS до `api.telegram.org` + - авторизуйте свою особу відправника (сполучення та/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи — `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість користувацьких команд/команд Plugin/Skills або вимкніть нативні меню + - `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми з доступністю DNS/HTTPS до `api.telegram.org` - + - - Node 22+ + custom fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спочатку визначають `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює спроби для них як для відновлюваних мережевих помилок. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і заново будує транспорт Telegram після 120 секунд без завершеної перевірки живучості long-poll за замовчуванням. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` працюють справно, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`. - - На VPS-хостах із нестабільним прямим egress/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 тепер повторює ці спроби як відновлювані мережеві помилки. + - Якщо в журналах є `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки живучості довгого опитування за типовим налаштуванням. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` є здоровими, але ваш хост усе ще повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або вихідним TLS між хостом і `api.telegram.org`. + - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -865,8 +865,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - За замовчуванням Node 22+ використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства: + - У Node 22+ типово встановлено `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. + - Якщо ваш хост — це WSL2 або він явно краще працює лише з IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -875,10 +875,10 @@ channels: autoSelectFamily: false ``` - - Відповіді з діапазону тестів RFC 2544 (`198.18.0.0/15`) уже дозволені - для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або - transparent proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете + - Відповіді діапазону RFC 2544 для бенчмарків (`198.18.0.0/15`) уже дозволені + типово для завантажень медіа Telegram. Якщо довірений fake-IP або + прозорий proxy переписує `api.telegram.org` на якусь іншу + приватну/внутрішню/спеціальну адресу під час завантаження медіа, можна явно ввімкнути обхід лише для Telegram: ```yaml @@ -891,21 +891,21 @@ channels: - Такий самий явний параметр доступний для окремого облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште - небезпечний прапорець вимкненим. Telegram media вже дозволяє діапазон тестів RFC 2544 - за замовчуванням. + небезпечний прапорець вимкненим. Медіа Telegram уже типово дозволяють + діапазон RFC 2544 для бенчмарків. `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram - media від SSRF. Використовуйте це лише в довірених керованих оператором - середовищах proxy, таких як Clash, Mihomo або Surge fake-IP routing, коли вони - синтезують приватні або спеціальні відповіді поза діапазоном тестів RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте це вимкненим. + media SSRF. Використовуйте його лише в довірених керованих оператором + середовищах proxy, як-от Clash, Mihomo або Surge з маршрутизацією fake-IP, коли вони + синтезують приватні або спеціальні відповіді поза діапазоном бенчмарку RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте цей параметр вимкненим. - Перевизначення через змінні середовища (тимчасово): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірка DNS-відповідей: + - Перевірте DNS-відповіді: ```bash dig +short api.telegram.org A @@ -917,21 +917,21 @@ dig +short api.telegram.org AAAA Більше довідки: [Усунення проблем каналу](/uk/channels/troubleshooting). -## Довідник config +## Довідник конфігурації -Основний довідник: [Configuration reference - Telegram](/uk/gateway/config-channels#telegram). +Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`) -- погодження exec: `execApprovals`, `accounts.*.execApprovals` -- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` +- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) +- схвалення exec: `execApprovals`, `accounts.*.execApprovals` +- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode` -- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -940,26 +940,26 @@ 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 для груп і тем. - - Маршрутизуйте вхідні повідомлення до агентів. + + Маршрутизація вхідних повідомлень до агентів. Модель загроз і посилення захисту. - Зіставляйте групи й теми з агентами. + Призначення груп і тем агентам. Міжканальна діагностика. diff --git a/docs/uk/concepts/streaming.md b/docs/uk/concepts/streaming.md index 838330657..3d751923b 100644 --- a/docs/uk/concepts/streaming.md +++ b/docs/uk/concepts/streaming.md @@ -1,29 +1,29 @@ --- read_when: - - Пояснення того, як працюють streaming або chunking у каналах - - Зміна поведінки потокового передавання блоків або chunking каналу - - Налагодження дубльованих/передчасних відповідей блоками або потокового передавання попереднього перегляду каналу -summary: Поведінка Streaming + chunking (відповіді блоками, потокове передавання попереднього перегляду каналу, зіставлення режимів) -title: Streaming і chunking + - Пояснення того, як працює потокова передача або розбиття на фрагменти в каналах + - Зміна поведінки блокової потокової передачі або розбиття каналу на фрагменти + - Налагодження дубльованих/передчасних блокових відповідей або потокової передачі попереднього перегляду каналу +summary: Поведінка потокової передачі + розбиття на фрагменти (блокові відповіді, потокова передача попереднього перегляду каналу, зіставлення режимів) +title: Потокова передача та розбиття на фрагменти x-i18n: - generated_at: "2026-04-25T12:04:27Z" + generated_at: "2026-04-26T22:47:47Z" model: gpt-5.4 provider: openai - source_hash: ba308b79b12886f3a1bc36bc277e3df0e2b9c6018aa260b432ccea89a235819f + source_hash: 7143421c98e8f4523e0f63653965ab0f63364d83f1073a6752385712551ec818 source_path: concepts/streaming.md workflow: 15 --- -OpenClaw має два окремі рівні streaming: +OpenClaw має два окремі шари потокової передачі: -- **Block streaming (канали):** надсилання завершених **блоків**, поки помічник пише. Це звичайні повідомлення каналу (не token deltas). -- **Preview streaming (Telegram/Discord/Slack):** оновлення тимчасового **повідомлення попереднього перегляду** під час генерації. +- **Блокова потокова передача (канали):** надсилає завершені **блоки**, коли помічник їх пише. Це звичайні повідомлення каналу (не дельти токенів). +- **Потокова передача попереднього перегляду (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації. -Справжнього streaming із token deltas до повідомлень каналу наразі **немає**. Preview streaming працює на рівні повідомлень (надсилання + редагування/додавання). +Справжньої потокової передачі дельт токенів у повідомлення каналу наразі **немає**. Потокова передача попереднього перегляду базується на повідомленнях (надсилання + редагування/додавання). -## Block streaming (повідомлення каналу) +## Блокова потокова передача (повідомлення каналу) -Block streaming надсилає вихідні дані помічника грубими порціями в міру їх появи. +Блокова потокова передача надсилає вивід помічника великими фрагментами в міру його появи. ``` Model output @@ -35,99 +35,92 @@ Model output └─ channel send (block replies) ``` -Легенда: +Позначення: -- `text_delta/events`: події потоку моделі (можуть бути розрідженими для моделей без streaming). -- `chunker`: `EmbeddedBlockChunker`, який застосовує мінімальні/максимальні межі + пріоритет розриву. -- `channel send`: фактичні вихідні повідомлення (відповіді блоками). +- `text_delta/events`: події потоку моделі (можуть бути рідкісними для моделей без потокової передачі). +- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + пріоритет розриву. +- `channel send`: фактичні вихідні повідомлення (блокові відповіді). **Керування:** -- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (`"off"` за замовчуванням). -- Перевизначення для каналу: `*.blockStreaming` (і варіанти для окремих облікових записів), щоб примусово встановити `"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? }` (об’єднання потокових блоків перед надсиланням). +- `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) розбиває високі відповіді, щоб уникнути обрізання в UI. **Семантика меж:** -- `text_end`: передавати блоки, щойно chunker їх видає; скидати на кожному `text_end`. -- `message_end`: чекати, доки завершиться повідомлення помічника, а потім скидати буферизований вміст. +- `text_end`: передавати блоки, щойно їх надсилає chunker; скидати на кожному `text_end`. +- `message_end`: чекати, доки повідомлення помічника завершиться, а потім скинути буферизований вивід. -`message_end` усе одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому наприкінці він може видати кілька фрагментів. +`message_end` все одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому в кінці він може надсилати кілька фрагментів. -### Доставка медіа з block streaming +### Доставка медіа з блоковою потоковою передачею -Директиви `MEDIA:` — це звичайні метадані доставки. Коли block streaming -рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне корисне навантаження помічника повторює ту саму URL-адресу медіа, фінальна доставка прибирає дублікат медіа замість повторного надсилання вкладення. +Директиви `MEDIA:` — це звичайні метадані доставки. Коли блокова потокова передача рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальний payload помічника повторює ту саму URL-адресу медіа, фінальна доставка прибирає дубльоване медіа замість повторного надсилання вкладення. -Точні дублікати фінального payload пригнічуються. Якщо фінальний payload додає -відмінний текст навколо медіа, яке вже було передано потоком, OpenClaw все одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових повідомлень або файлів у таких каналах, як Telegram, коли агент надсилає `MEDIA:` під час streaming, а провайдер також включає його до завершеної відповіді. +Точні дублікати фінального payload не надсилаються. Якщо фінальний payload додає окремий текст навколо медіа, яке вже було передано в потоці, OpenClaw усе одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових повідомлень або файлів у таких каналах, як Telegram, коли агент надсилає `MEDIA:` під час потокової передачі, а провайдер також включає його в завершену відповідь. -## Алгоритм chunking (нижня/верхня межі) +## Алгоритм розбиття на фрагменти (нижня/верхня межі) -Block chunking реалізовано в `EmbeddedBlockChunker`: +Розбиття блоків реалізовано в `EmbeddedBlockChunker`: -- **Нижня межа:** не видавати, доки буфер < `minChars` (якщо не примусово). -- **Верхня межа:** намагатися розбивати до `maxChars`; якщо примусово, розбивати на `maxChars`. +- **Нижня межа:** не надсилати, доки буфер не досягне `minChars` (якщо не примусово). +- **Верхня межа:** намагатися розбити до `maxChars`; якщо примусово, розбивати на `maxChars`. - **Пріоритет розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. -- **Code fences:** ніколи не розбивати всередині fences; коли примусово на `maxChars`, закривати й знову відкривати fence, щоб Markdown залишався коректним. +- **Огорожі коду:** ніколи не розбивати всередині них; у разі примусового розбиття на `maxChars` закривати й знову відкривати огорожу, щоб Markdown залишався коректним. -`maxChars` обмежується значенням канального `textChunkLimit`, тому перевищити ліміти для конкретного каналу не можна. +`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити ліміти конкретного каналу неможливо. -## Coalescing (об’єднання потокових блоків) +## Об’єднання (злиття блоків із потоку) -Коли block streaming увімкнено, OpenClaw може **об’єднувати послідовні block chunks** -перед їх надсиланням. Це зменшує “спам із одного рядка”, але при цьому зберігає -поступове виведення. +Коли блокову потокову передачу увімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їх надсиланням. Це зменшує «спам одним рядком», але водночас забезпечує поступову доставку виводу. -- Coalescing чекає на **паузи без активності** (`idleMs`) перед скиданням. -- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать його. -- `minChars` не дає надсилати надто малі фрагменти, доки не накопичиться достатньо тексту - (фінальне скидання завжди надсилає залишковий текст). -- Роздільник визначається з `blockStreamingChunk.breakPreference` +- Об’єднання чекає **пауз без активності** (`idleMs`) перед скиданням. +- Буфери обмежені `maxChars` і будуть скинуті, якщо перевищать це значення. +- `minChars` не дає надсилати надто малі фрагменти, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишковий текст). +- Розділювач визначається з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл). -- Перевизначення для каналу доступні через `*.blockStreamingCoalesce` (зокрема в конфігураціях окремих облікових записів). -- Значення coalesce `minChars` за замовчуванням підвищується до `1500` для Signal/Slack/Discord, якщо не перевизначено. +- Доступні перевизначення на рівні каналу через `*.blockStreamingCoalesce` (зокрема конфігурації для окремих акаунтів). +- Типове значення coalesce `minChars` підвищується до 1500 для Signal/Slack/Discord, якщо не перевизначено. -## Людиноподібна пауза між блоками +## Людиноподібний ритм між блоками -Коли block streaming увімкнено, можна додати **випадкову паузу** між -відповідями блоками (після першого блоку). Це робить відповіді з кількох бульбашок природнішими. +Коли блокову потокову передачу увімкнено, можна додати **випадкову паузу** між блоковими відповідями (після першого блока). Це робить багатобульбашкові відповіді природнішими. - Конфігурація: `agents.defaults.humanDelay` (можна перевизначити для агента через `agents.list[].humanDelay`). -- Режими: `off` (за замовчуванням), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`). -- Застосовується лише до **відповідей блоками**, а не до фінальних відповідей чи підсумків інструментів. +- Режими: `off` (типово), `natural` (800–2500 мс), `custom` (`minMs`/`maxMs`). +- Застосовується лише до **блокових відповідей**, а не до фінальних відповідей або підсумків інструментів. -## "Stream chunks or everything" +## «Передавати фрагменти чи все» -Це зіставляється так: +Це відповідає таким налаштуванням: -- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (видавати в процесі). Для каналів, окрім Telegram, також потрібно `*.blockStreaming: true`. -- **Stream everything at end:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо, кількома фрагментами, якщо відповідь дуже довга). -- **No block streaming:** `blockStreamingDefault: "off"` (лише фінальна відповідь). +- **Передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (надсилати в міру готовності). Для каналів, відмінних від Telegram, також потрібно `*.blockStreaming: true`. +- **Передати все наприкінці:** `blockStreamingBreak: "message_end"` (одне скидання, можливо з кількома фрагментами, якщо текст дуже довгий). +- **Без блокової потокової передачі:** `blockStreamingDefault: "off"` (лише фінальна відповідь). -**Примітка щодо каналів:** Block streaming **вимкнено, доки** -`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий preview -(`channels..streaming`) без відповідей блоками. +**Примітка щодо каналів:** Блокова потокова передача **вимкнена, якщо тільки** +`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд (`channels..streaming`) без блокових відповідей. -Нагадування про розташування конфігурації: значення за замовчуванням `blockStreaming*` знаходяться в `agents.defaults`, а не в корені конфігурації. +Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в корені конфігурації. -## Режими preview streaming +## Режими потокової передачі попереднього перегляду Канонічний ключ: `channels..streaming` Режими: -- `off`: вимкнути preview streaming. -- `partial`: один preview, який замінюється найсвіжішим текстом. -- `block`: preview оновлюється chunked/appended-кроками. -- `progress`: preview прогресу/статусу під час генерації, фінальна відповідь після завершення. +- `off`: вимкнути потокову передачу попереднього перегляду. +- `partial`: один попередній перегляд, який замінюється найновішим текстом. +- `block`: оновлення попереднього перегляду поетапними фрагментами/додаваннями. +- `progress`: попередній перегляд статусу/прогресу під час генерації, фінальна відповідь після завершення. -### Зіставлення каналів +### Відповідність каналів | Канал | `off` | `partial` | `block` | `progress` | | ---------- | ----- | --------- | ------- | ----------------- | @@ -138,60 +131,61 @@ Block chunking реалізовано в `EmbeddedBlockChunker`: Лише для Slack: -- `channels.slack.streaming.nativeTransport` перемикає виклики нативного Slack streaming API, коли `channels.slack.streaming.mode="partial"` (`true` за замовчуванням). -- Нативний Slack streaming і статус потоку помічника в Slack thread вимагають цільового потоку відповіді; DM верхнього рівня не показують такий preview у стилі thread. +- `channels.slack.streaming.nativeTransport` вмикає/вимикає власні виклики API потокової передачі Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`). +- Власна потокова передача Slack і статус потоку помічника Slack вимагають ціль відповіді у гілці; DM верхнього рівня не показують такий попередній перегляд у стилі гілки. Міграція застарілих ключів: -- Telegram: застарілі `streamMode` і скалярні/булеві значення `streaming` виявляються та мігруються шляхами doctor/config compatibility до `streaming.mode`. -- Discord: `streamMode` + булеве `streaming` автоматично мігрують до enum `streaming`. -- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булеве `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`. +- Telegram: застарілі `streamMode` і скалярні/булеві значення `streaming` виявляються й переносяться шляхами doctor/config compatibility до `streaming.mode`. +- Discord: `streamMode` + булевий `streaming` автоматично переносяться до enum `streaming`. +- Slack: `streamMode` автоматично переноситься до `streaming.mode`; булевий `streaming` автоматично переноситься до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично переноситься до `streaming.nativeTransport`. ### Поведінка під час виконання Telegram: -- Використовує `sendMessage` + `editMessageText` для оновлень preview у DM, групах і темах. -- Preview streaming пропускається, якщо для Telegram явно увімкнено block streaming (щоб уникнути подвійного streaming). -- `/reasoning stream` може записувати reasoning у preview. +- Використовує оновлення попереднього перегляду через `sendMessage` + `editMessageText` у DM і групах/темах. +- Надсилає нове фінальне повідомлення замість редагування на місці, якщо попередній перегляд був видимий приблизно одну хвилину, а потім прибирає його, щоб мітка часу Telegram відображала завершення відповіді. +- Потокова передача попереднього перегляду пропускається, якщо блокову потокову передачу Telegram явно ввімкнено (щоб уникнути подвійної потокової передачі). +- `/reasoning stream` може записувати міркування до попереднього перегляду. Discord: -- Використовує надсилання + редагування preview-повідомлень. -- Режим `block` використовує чернетковий chunking (`draftChunk`). -- Preview streaming пропускається, якщо для Discord явно увімкнено block streaming. -- Фінальні payload для медіа, помилок і explicit reply скасовують очікувані preview без скидання нової чернетки, а потім використовують звичайну доставку. +- Використовує надсилання + редагування повідомлень попереднього перегляду. +- Режим `block` використовує чернеткове розбиття (`draftChunk`). +- Потокова передача попереднього перегляду пропускається, якщо блокову потокову передачу Discord явно ввімкнено. +- Фінальні payload для медіа, помилок і явних відповідей скасовують очікувані попередні перегляди без скидання нової чернетки, а потім використовують звичайну доставку. Slack: -- `partial` може використовувати нативний Slack streaming (`chat.startStream`/`append`/`stop`), якщо доступний. -- `block` використовує preview чернеток у стилі append. -- `progress` використовує текст preview статусу, а потім фінальну відповідь. -- Нативний і чернетковий preview streaming пригнічують block replies для цього ходу, тому відповідь Slack передається лише одним шляхом доставки. -- Фінальні payload для медіа/помилок і фінали progress не створюють тимчасових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати preview, скидають очікуваний текст чернетки. +- `partial` може використовувати власну потокову передачу Slack (`chat.startStream`/`append`/`stop`), якщо вона доступна. +- `block` використовує попередні перегляди чернеток у стилі додавання. +- `progress` використовує текст попереднього перегляду статусу, а потім фінальну відповідь. +- Власна та чернеткова потокова передача попереднього перегляду пригнічують блокові відповіді для цього ходу, тож відповідь Slack передається лише одним шляхом доставки. +- Фінальні payload для медіа/помилок і фінали progress не створюють тимчасових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний текст чернетки. Mattermost: -- Передає thinking, активність інструментів і частковий текст відповіді в один чернетковий preview post, який фіналізується на місці, коли фінальну відповідь уже безпечно надсилати. -- Повертається до надсилання нового фінального post, якщо preview post було видалено або він інакше недоступний на момент фіналізації. -- Фінальні payload для медіа/помилок скасовують очікувані оновлення preview перед звичайною доставкою замість скидання тимчасового preview post. +- Передає міркування, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь можна безпечно надіслати. +- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний у момент фіналізації. +- Фінальні payload для медіа/помилок скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасового допису попереднього перегляду. Matrix: -- Чернеткові preview фіналізуються на місці, коли фінальний текст може повторно використати подію preview. -- Фінали лише з медіа, з помилками та з невідповідністю цілі reply скасовують очікувані оновлення preview перед звичайною доставкою; уже видимий застарілий preview редагується. +- Чернеткові попередні перегляди фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. +- Фінали лише з медіа, з помилками і з невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується. -### Оновлення preview із прогресом інструментів +### Оновлення попереднього перегляду прогресу інструментів -Preview streaming також може включати оновлення **tool-progress** — короткі рядки статусу на кшталт "searching the web", "reading file" або "calling tool", — які з’являються в тому самому preview-повідомленні під час роботи інструментів, до фінальної відповіді. Це робить багатокрокові ходи з інструментами візуально активними, а не мовчазними між першим preview мислення і фінальною відповіддю. +Потокова передача попереднього перегляду також може включати оновлення **прогресу інструментів** — короткі рядки стану на кшталт «пошук у вебі», «читання файла» або «виклик інструмента», які з’являються в тому самому повідомленні попереднього перегляду під час роботи інструментів, ще до фінальної відповіді. Це робить багатоетапні ходи з інструментами візуально активними, а не мовчазними між першим попереднім переглядом міркувань і фінальною відповіддю. Підтримувані поверхні: -- **Discord**, **Slack** і **Telegram** за замовчуванням передають tool-progress у live preview edit, коли preview streaming активний. -- Для Telegram оновлення preview з tool-progress постачаються увімкненими з `v2026.4.22`; збереження їх увімкненими підтримує вже випущену поведінку. -- **Mattermost** уже включає активність інструментів у свій один чернетковий preview post (див. вище). -- Редагування tool-progress наслідують активний режим preview streaming; вони пропускаються, коли preview streaming має значення `off` або коли block streaming уже взяв повідомлення під контроль. -- Щоб зберегти preview streaming, але приховати рядки tool-progress, установіть `streaming.preview.toolProgress` в `false` для цього каналу. Щоб повністю вимкнути редагування preview, установіть `streaming.mode` в `off`. +- **Discord**, **Slack** і **Telegram** типово передають прогрес інструментів у живе редагування попереднього перегляду, коли потокову передачу попереднього перегляду активовано. +- Для Telegram оновлення попереднього перегляду прогресу інструментів увімкнено в релізі, починаючи з `v2026.4.22`; збереження цього стану підтримує вже випущену поведінку. +- **Mattermost** уже включає активність інструментів у свій єдиний чернетковий допис попереднього перегляду (див. вище). +- Редагування прогресу інструментів дотримуються активного режиму потокової передачі попереднього перегляду; вони пропускаються, коли потокову передачу попереднього перегляду вимкнено (`off`) або коли керування повідомленням перебрала блокова потокова передача. +- Щоб зберегти потокову передачу попереднього перегляду, але приховати рядки прогресу інструментів, установіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, установіть `streaming.mode` у `off`. Приклад: @@ -212,6 +206,6 @@ Preview streaming також може включати оновлення **tool ## Пов’язане -- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлення й доставка +- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлення та доставка - [Повторні спроби](/uk/concepts/retry) — поведінка повторних спроб у разі збою доставки -- [Канали](/uk/channels) — підтримка streaming для кожного каналу +- [Канали](/uk/channels) — підтримка потокової передачі для окремих каналів