From 98d36c4e1eee73071833b0bbba26365eb32eefad Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 15:50:05 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/telegram.md | 454 +++++++++++++++++----------------- docs/uk/concepts/streaming.md | 160 ++++++------ 2 files changed, 306 insertions(+), 308 deletions(-) diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 5ef77882e..574d11054 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,28 +1,28 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Статус підтримки Telegram-бота, можливості та конфігурація +summary: Статус підтримки бота Telegram, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-05-03T15:25:57Z" + generated_at: "2026-05-03T15:47:48Z" model: gpt-5.5 provider: openai - source_hash: c3b97d3dff3d3a91db568dc689f82c0b63ad8028fb716cc772e84d7afe071869 + source_hash: 5f234bc5f33eacbed3bfdc9d60285ea22ce4747f727cdb13863732238470a62d source_path: channels/telegram.md workflow: 16 --- -Готово до продакшену для особистих повідомлень ботам і груп через grammY. Long polling є режимом за замовчуванням; режим webhook є необов'язковим. +Готово для продакшену для особистих повідомлень ботам і груп через grammY. Long polling є режимом за замовчуванням; режим webhook є необов’язковим. Політика особистих повідомлень за замовчуванням для Telegram — сполучення. - Міжканальна діагностика та плейбуки відновлення. + Діагностика між каналами та інструкції з відновлення. - Повні шаблони й приклади конфігурації каналів. + Повні шаблони та приклади конфігурації каналів. @@ -32,7 +32,7 @@ x-i18n: Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). - Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. + Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. @@ -52,11 +52,11 @@ x-i18n: ``` Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. - + ```bash openclaw gateway @@ -64,12 +64,12 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення діють 1 годину. + Коди сполучення спливають через 1 годину. - Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до своєї моделі доступу. @@ -83,12 +83,12 @@ openclaw pairing approve telegram Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі групові повідомлення, виконайте одне з двох: + Якщо бот має бачити всі групові повідомлення, зробіть одне з такого: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Під час перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. @@ -111,28 +111,28 @@ openclaw pairing approve telegram - `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: + `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: - `pairing` (за замовчуванням) - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`) - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає username бота, давати команди боту. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `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 мали явний обліковий запис оператора. + Авторизація відправника в групі все одно походить із явних allowlists у конфігурації. + Якщо ви хочете "я авторизований один раз, і працюють як особисті повідомлення, так і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram @@ -152,12 +152,12 @@ curl "https://api.telegram.org/bot/getUpdates" - + Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає config `groups`: - - з `groupPolicy: "open"`: будь-яка група може пройти перевірки group-ID + - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - `groups` налаштовано: діє як allowlist (явні ID або `"*"`) @@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від'ємні ID чатів належать у `channels.telegram.groups`. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`. Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує підтвердження зі сховища сполучень для особистих повідомлень. - Сполучення лишається тільки для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Межа безпеки (`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` не задано явно. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -213,16 +213,16 @@ curl "https://api.telegram.org/bot/getUpdates" Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. - - Додавайте від'ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. + - Використовуйте `groupAllowFrom: ["*"]` лише коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. - Відповіді в групі за замовчуванням потребують згадки. + Групові відповіді за замовчуванням потребують згадки. Згадка може походити з: @@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд рівня сесії: + Перемикачі команд на рівні сесії: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Використовуйте config для збереження. + Вони оновлюють лише стан сесії. Для збереження використовуйте config. Приклад сталої конфігурації: @@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь назад у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та placeholders для медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми лишалися ізольованими. -- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID thread для відповідей, але за замовчуванням тримає особисті повідомлення в пласкій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію topic, коли ви навмисно хочете ізоляцію сесій тем в особистих повідомленнях. -- Long polling використовує grammY runner із послідовністю per-chat/per-thread. Загальна конкуренція runner sink використовує `agents.defaults.maxConcurrent`. -- Long polling захищений усередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller. -- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час довготривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються override для окремих облікових записів. -- Telegram Bot API не має підтримки read-receipt (`sendReadReceipts` не застосовується). +- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа. +- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими. +- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням тримає особисті повідомлення в плоскій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій тем в особистих повідомленнях. +- Long polling використовує grammY runner із послідовністю за чатами/потоками. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. +- Long polling захищений усередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller. +- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеного liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - - прямі чати: повідомлення попереднього перегляду + `editMessageText` - - групи/теми: повідомлення попереднього перегляду + `editMessageText` + - прямі чати: повідомлення preview + `editMessageText` + - групи/теми: повідомлення preview + `editMessageText` Вимога: - - `channels.telegram.streaming` є `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` мапиться на `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна streaming попереднього перегляду) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх у `channels.telegram.streaming.mode` + - `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`) + - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення preview (за замовчуванням: `true`, коли preview streaming активний) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і новіших версій. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення preview для прогресу інструментів — це короткі рядки "Працюємо...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати поведінці OpenClaw, випущеній у `v2026.4.22` і пізніше. Щоб зберегти редагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,16 +306,20 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання окремими повідомленнями "Working...". Запити на схвалення, медіанавантаження та помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно залишити лише редагування попереднього перегляду відповіді, приховавши рядки стану прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду в Telegram вимикається, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремих повідомлень "Working...". Запити на схвалення, медіа-вміст і помилки й далі проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. - Для відповідей лише з текстом: + + Відповіді Telegram на вибрані цитати є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний механізм Telegram для відповідей із цитатою замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показувати короткі рядки "Working..." для такого звернення. Відповіді на поточне повідомлення без тексту вибраної цитати й далі зберігають потоковий попередній перегляд. Встановіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді з цитатою, або встановіть `streaming.preview.toolProgress: false`, щоб прийняти цей компроміс. + - - короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду + Для текстових відповідей: - Для складних відповідей (наприклад, медіанавантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + - короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, тому видима часова позначка Telegram відображає час завершення, а не час створення попереднього перегляду - Потокове передавання попереднього перегляду окреме від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду. + + Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Потік міркувань лише для Telegram: @@ -324,25 +328,25 @@ curl "https://api.telegram.org/bot/getUpdates" - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Markdown-подібний текст рендериться у безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. + - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. + - Необроблений HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. + - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як простий текст. - Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені за допомогою `channels.telegram.linkPreview: false`. + Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. + + Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`. - Типові значення для вбудованих команд: + Типові значення нативних команд: - - `commands.native: "auto"` вмикає вбудовані команди для Telegram + - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте власні записи меню команд: + Додайте користувацькі записи меню команд: ```json5 { @@ -359,47 +363,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - - дійсний шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - власні команди не можуть перевизначати вбудовані команди - - конфлікти/дублікати пропускаються та записуються в журнал + - назви нормалізуються (прибирається початковий `/`, переводяться в нижній регістр) + - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` + - користувацькі команди не можуть перевизначати нативні команди + - конфлікти/дублікати пропускаються й логуються Примітки: - - власні команди є лише записами меню; вони не реалізують поведінку автоматично - - команди Plugin/skill усе одно можуть працювати під час введення, навіть якщо їх не показано в меню Telegram + - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично + - команди Plugin/Skills можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо вбудовані команди вимкнено, вбудовані записи видаляються. Власні команди/команди Plugin усе одно можуть реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть і далі реєструватися, якщо це налаштовано. - Поширені помилки налаштування: + Поширені збої налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`. - - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, тоді як прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було задано як повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як збій очищення Webhook. - - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблокований. + - `setMyCommands failed` із `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. + - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` із `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/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` заблоковано. - ### Команди сполучення пристроїв (Plugin `device-pair`) + ### Команди сполучення пристрою (Plugin `device-pair`) - Коли встановлено Plugin `device-pair`: + Коли Plugin `device-pair` встановлено: 1. `/pair` генерує код налаштування - 2. вставте код в iOS app - 3. `/pair pending` показує очікувані запити (зокрема роль/області) + 2. вставте код у застосунок iOS + 3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями дії) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один очікуваний запит - `/pair approve latest` для найновішого - Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла з `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролям, що не є операторами, усе ще потрібні області під власним префіксом ролі. + Код налаштування містить короткочасний 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). - - Налаштуйте область inline-клавіатури: + + Налаштуйте область дії вбудованої клавіатури: ```json5 { @@ -431,7 +435,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Області: + Області дії: - `off` - `dm` @@ -439,7 +443,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. Приклад дії повідомлення: @@ -459,40 +463,40 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Натискання callback передаються агенту як текст: + Натискання зворотних викликів передаються агенту як текст: `callback_data: ` - + Дії інструментів 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`). + Дії повідомлень каналу надають зручні псевдоніми (`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` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` зараз увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують довільне повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги потоків відповідей у згенерованому виводі: + + Telegram підтримує явні теги гілок відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що запустило дію + - `[[reply_to_current]]` відповідає на повідомлення, що запустило обробку - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -501,29 +505,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:` - - відповіді та typing спрямовуються в потік теми + - ключі сеансів теми додають `:topic:` + - відповіді та індикатор набору тексту спрямовуються в гілку теми - шлях конфігурації теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії typing усе одно включають `message_thread_id` + - дії набору тексту все одно містять `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` застосовується лише до теми й не успадковується з типових значень групи. - **Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента, якщо встановити `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агента для окремої теми**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад: ```json5 { @@ -543,26 +547,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Після цього кожна тема має власний ключ сеансу: `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`). + **Створення thread-bound ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються безпосередньо туди. OpenClaw закріплює підтвердження створення в темі. Потребує, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають DM-маршрутизацію й метадані відповіді у пласких сесіях; вони використовують thread-aware ключі сесій лише коли налаштовано `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. - + ### Аудіоповідомлення - Telegram розрізняє голосові нотатки й аудіофайли. + Telegram розрізняє голосові нотатки та аудіофайли. - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку - - вхідні транскрипти голосових нотаток оформлюються як машинно згенерований, - недовірений текст у контексті агента; виявлення згадки все одно використовує сирий - транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. + - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, + ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий + транскрипт, тому голосові повідомлення з обмеженням за згадкою й далі працюють. Приклад дії повідомлення: @@ -578,7 +582,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли й відеонотатки. + Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: @@ -598,7 +602,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується та обробляється (placeholder ``) + - статичний WEBP: завантажується й обробляється (placeholder ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -614,9 +618,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики розпізнавання зображень. - Увімкніть дії зі стікерами: + Увімкнути дії зі стікерами: ```json5 { @@ -630,7 +634,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Надіслати дію стікера: + Дія надсилання стікера: ```json5 { @@ -641,7 +645,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Шукати кешовані стікери: + Пошук кешованих стікерів: ```json5 { @@ -655,53 +659,53 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень). - Коли це ввімкнено, OpenClaw додає в чергу системні події на кшталт: + Коли ввімкнено, OpenClaw додає в чергу системні події на кшталт: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` Конфігурація: - - `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 не надає ідентифікатори гілок в оновленнях реакцій. - - групи без форумів спрямовуються до сеансу групового чату - - групи з форумами спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). + - Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає thread IDs в оновленнях реакцій. + - групи без форумів спрямовуються до сесії групового чату + - групи-форуми спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для опитування/webhook автоматично включає `message_reaction`. + `allowed_updates` для polling/webhook автоматично включає `message_reaction`. - - `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. + + `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує емодзі Unicode (наприклад "👀"). - - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Telegram очікує unicode emoji (наприклад, "👀"). + - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнені за замовчуванням (`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` (потрібне ввімкнення команди) Вимкнути: @@ -717,31 +721,31 @@ 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"`. + Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим webhook перевіряє захисні умови запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі лінії бота для кожного чату/теми, що використовуються тривалим опитуванням, тож повільні ходи агента не затримують ACK доставки Telegram. + Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON body перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі per-chat/per-topic bot lanes, що й long polling, тому повільні ходи агента не затримують delivery ACK Telegram. - - - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. + + - `channels.telegram.textChunkLimit` типово дорівнює 4000. - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується стандарт grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисного ліміту вихідних текстових/typing-запитів, щоб grammY не переривав доставку видимої відповіді до того, як зможуть спрацювати транспортний захист і резервний механізм OpenClaw. Тривале опитування все ще використовує 45-секундний захисний ліміт запиту `getUpdates`, щоб бездіяльні опитування не залишалися покинутими безкінечно. - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування. - - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. - - Списки дозволів Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - - Елементи керування історією DM: + - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. + - `channels.telegram.timeoutSeconds` перевизначає таймаут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного guard для вихідних текстових/typing запитів, щоб grammY не переривав доставку видимої відповіді до того, як зможуть спрацювати transport guard і fallback OpenClaw. Long polling усе ще використовує 45-секундний guard запиту `getUpdates`, щоб idle polls не залишалися покинутими безстроково. + - `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; змінюйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків polling-stall. + - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. + - додатковий контекст reply/quote/forward наразі передається в отриманому вигляді. + - Allowlist-и Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до помічників надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до встановлення з’єднання, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений safe-send retry для збоїв Telegram pre-connect, але не повторює неоднозначні post-send network envelopes, які можуть дублювати видимі повідомлення. - Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача: + Ціль надсилання CLI може бути числовим chat ID або username: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" @@ -763,13 +767,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для тем форуму (або використайте ціль `:topic:`) + - `--thread-id` для тем форумів (або використовуйте ціль `:topic:`) Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення й GIF як документи замість стиснених фото або завантажень анімованих медіа + - `--presentation` з блоками `buttons` для inline keyboards, коли це дозволяє `channels.telegram.capabilities.inlineButtons` + - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті + - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media Обмеження дій: @@ -778,37 +782,37 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - - Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ідентифікаторами користувачів Telegram. + + Telegram підтримує exec approvals в DM approver-ів і може додатково публікувати prompts у початковому чаті або темі. Approver-и мають бути числовими Telegram user IDs. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача) - - `channels.telegram.execApprovals.approvers` (повертається до числових ідентифікаторів власників із `commands.ownerAllowFrom`) - - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного approver-а) + - `channels.telegram.execApprovals.approvers` (fallback до числових owner IDs із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене спарювання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ідентифікаторів у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver-ом. Перше схвалене pairing DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе одно працює без дублювання IDs у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Схвалення exec за замовчуванням спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє в тему форуму, OpenClaw зберігає тему для prompt схвалення і follow-up. Exec approvals типово спливають через 30 хвилин. - Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Ідентифікатори схвалення з префіксом `plugin:` розв’язуються через схвалення Plugin; інші спершу розв’язуються через схвалення exec. + Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Approval IDs із префіксом `plugin:` визначаються через plugin approvals; інші спершу визначаються через exec approvals. - Див. [Схвалення exec](/uk/tools/exec-approvals). + Див. [Exec approvals](/uk/tools/exec-approvals). -## Елементи керування відповідями про помилки +## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або provider-а, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації: -| Ключ | Значення | За замовчуванням | Опис | -| ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | -| `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` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для кожного облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram). +Підтримуються перевизначення для облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram). ```json5 { @@ -831,54 +835,54 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. + - Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть і знову додайте бота до групи + - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство. - - швидкий тест сеансу: `/activation always`. + - `openclaw channels status --probe` може перевіряти явні числові group IDs; wildcard `"*"` не можна перевірити на membership. + - швидкий тест сесії: `/activation always`. - - коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`) - - перевірте членство бота в групі - - перегляньте журнали: `openclaw logs --follow` для причин пропуску + - коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`) + - перевірте membership бота в групі + - перегляньте логи: `openclaw logs --follow` для причин пропуску - + - - авторизуйте свою ідентичність відправника (спарювання та/або числовий `allowFrom`) - - авторизація команд усе ще застосовується, навіть коли політика групи має значення `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть нативні меню - - Виклики запуску `deleteMyCommands` / `setMyCommands` і typing-виклики `sendChatAction` обмежені та повторюються один раз через транспортний резерв Telegram у разі тайм-ауту запиту. Постійні мережеві/fetch-помилки зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` + - авторизуйте вашу sender identity (pairing та/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли group policy має значення `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в native menu забагато записів; зменште кількість plugin/skill/custom commands або вимкніть native menus + - стартові виклики `deleteMyCommands` / `setMyCommands` і typing-виклики `sendChatAction` обмежені й повторюються один раз через transport fallback Telegram при request timeout. Постійні network/fetch errors зазвичай вказують на проблеми 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. + - `getMe returned 401` — це збій автентифікації Telegram для налаштованого bot token. + - Скопіюйте повторно або згенеруйте заново bot token у BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. + - `deleteWebhook 401 Unauthorized` під час запуску також є збоєм auth; трактування цього як "no webhook exists" лише відклало б той самий збій bad-token до пізніших API calls. - + - - Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спершу розв'язують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram 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, щоб виконавцю не був потрібен другий `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 також враховує proxy-змінні середовища процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища, а стандартні proxy-змінні середовища відсутні, Telegram також використовує цей URL для транспорту Bot API. - - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Під час запуску опитування 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 також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартних змінних середовища proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API. + - На VPS-хостах із нестабільним прямим виходом/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -886,7 +890,7 @@ 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`. + - 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 @@ -896,10 +900,10 @@ channels: autoSelectFamily: false ``` - - Відповіді діапазону RFC 2544 для бенчмарків (`198.18.0.0/15`) уже дозволені - для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або - прозорий proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете + - Відповіді з діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені + для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або + прозорий proxy переписує `api.telegram.org` на іншу + приватну/внутрішню/спеціальну адресу під час завантаження медіа, ви можете увімкнути обхід лише для Telegram: ```yaml @@ -909,18 +913,14 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Такий самий явний дозвіл доступний для кожного облікового запису в + - Та сама опція доступна для кожного облікового запису за адресою `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, коли вони - синтезують приватні відповіді або відповіді спеціального призначення поза діапазоном - бенчмарків RFC 2544. Залишайте це вимкненим для звичайного публічного інтернет-доступу до Telegram. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти SSRF для медіа Telegram. Використовуйте це лише в довірених, контрольованих оператором середовищах proxy, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони синтезують приватні чи спеціальні відповіді поза діапазоном RFC 2544 для бенчмаркінгу. Залишайте це вимкненим для звичайного доступу Telegram через публічний інтернет. - Перевизначення середовища (тимчасові): @@ -937,24 +937,24 @@ dig +short api.telegram.org AAAA -Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting). +Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + -- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) +- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) - контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) -- схвалення exec: `execApprovals`, `accounts.*.execApprovals` +- підтвердження 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`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -963,7 +963,7 @@ dig +short api.telegram.org AAAA -Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `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.*`. ## Пов’язане @@ -973,7 +973,7 @@ dig +short api.telegram.org AAAA Сполучіть користувача Telegram із Gateway. - Поведінка списку дозволених груп і тем. + Поведінка allowlist для груп і тем. Маршрутизуйте вхідні повідомлення до агентів. @@ -981,7 +981,7 @@ dig +short api.telegram.org AAAA Модель загроз і посилення захисту. - + Зіставляйте групи й теми з агентами. diff --git a/docs/uk/concepts/streaming.md b/docs/uk/concepts/streaming.md index 84d8f23e4..1cf7e8697 100644 --- a/docs/uk/concepts/streaming.md +++ b/docs/uk/concepts/streaming.md @@ -2,28 +2,28 @@ read_when: - Пояснення того, як потокове передавання або розбиття на фрагменти працює в каналах - Зміна поведінки потокового передавання блоків або розбиття каналу на фрагменти - - Налагодження дубльованих/передчасних блокових відповідей або потокової передачі попереднього перегляду каналу + - Налагодження дубльованих/передчасних блокових відповідей або потокового передавання попереднього перегляду каналу summary: Поведінка потокового передавання та розбиття на фрагменти (блокові відповіді, потокове передавання попереднього перегляду каналу, зіставлення режимів) -title: Потокове передавання та поділ на фрагменти +title: Потокове передавання та розбиття на фрагменти x-i18n: - generated_at: "2026-05-03T01:35:00Z" + generated_at: "2026-05-03T15:48:04Z" model: gpt-5.5 provider: openai - source_hash: 85f6cb33031a6c818bb709e0ed14d8dd0f8c30a3dd90468a40396b3a515b5e65 + source_hash: 4a62b333123d317cad9a8063a68c5c026fb91b23731a6ccdb97d995d9bb8bdba source_path: concepts/streaming.md workflow: 16 --- OpenClaw має два окремі рівні потокової передачі: -- **Блокова потокова передача (канали):** надсилає завершені **блоки**, коли асистент пише. Це звичайні повідомлення каналів (не дельти токенів). +- **Потокова передача блоків (канали):** надсилає завершені **блоки** під час написання асистентом. Це звичайні повідомлення каналів (не дельти токенів). - **Потоковий попередній перегляд (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації. -Сьогодні **немає справжньої потокової передачі дельт токенів** у повідомлення каналів. Потоковий попередній перегляд працює на рівні повідомлень (надсилання + редагування/додавання). +Сьогодні **справжньої потокової передачі дельт токенів** у повідомлення каналів немає. Потоковий попередній перегляд працює на основі повідомлень (надсилання + редагування/додавання). -## Блокова потокова передача (повідомлення каналів) +## Потокова передача блоків (повідомлення каналів) -Блокова потокова передача надсилає вивід асистента великими фрагментами, щойно вони стають доступними. +Потокова передача блоків надсилає вивід асистента великими фрагментами в міру їх появи. ``` Model output @@ -35,81 +35,78 @@ Model output └─ channel send (block replies) ``` -Позначення: +Легенда: - `text_delta/events`: події потоку моделі (можуть бути розрідженими для непотокових моделей). -- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + пріоритет розриву. +- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + бажаний розрив. - `channel send`: фактичні вихідні повідомлення (блокові відповіді). **Елементи керування:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (типово вимкнено). -- Перевизначення каналів: `*.blockStreaming` (і варіанти для окремих облікових записів), щоб примусово встановити `"on"`/`"off"` для кожного каналу. +- Перевизначення каналів: `*.blockStreaming` (і варіанти для окремих акаунтів), щоб примусово встановити `"on"`/`"off"` для кожного каналу. - `agents.defaults.blockStreamingBreak`: `"text_end"` або `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об'єднує потокові блоки перед надсиланням). +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднання потокових блоків перед надсиланням). - Жорстке обмеження каналу: `*.textChunkLimit` (наприклад, `channels.whatsapp.textChunkLimit`). -- Режим фрагментації каналу: `*.chunkMode` (`length` типово, `newline` розділяє за порожніми рядками (межами абзаців) перед фрагментацією за довжиною). -- М'яке обмеження Discord: `channels.discord.maxLinesPerMessage` (типово 17) розділяє високі відповіді, щоб уникнути обрізання в інтерфейсі. +- Режим фрагментації каналу: `*.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`, тому наприкінці може видати кілька фрагментів. -### Доставка медіа з блоковою потоковою передачею +### Доставка медіа з потоковою передачею блоків -Директиви `MEDIA:` є звичайними метаданими доставки. Коли блокова потокова передача рано надсилає медіаблок, OpenClaw запам'ятовує цю доставку для поточного звернення. Якщо фінальне навантаження асистента повторює той самий URL медіа, фінальна доставка вилучає дубль медіа замість повторного надсилання вкладення. +Директиви `MEDIA:` є звичайними метаданими доставки. Коли потокова передача блоків рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне навантаження асистента повторює ту саму URL-адресу медіа, фінальна доставка вилучає дубльоване медіа замість повторного надсилання вкладення. -Точні дублікати фінальних навантажень пригнічуються. Якщо фінальне навантаження додає окремий текст навколо медіа, яке вже було передано потоком, OpenClaw все одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових нотаток або файлів у таких каналах, як Telegram, коли агент видає `MEDIA:` під час потокової передачі, а провайдер також включає його до завершеної відповіді. +Точні дублікати фінальних навантажень пригнічуються. Якщо фінальне навантаження додає окремий текст навколо медіа, яке вже було передано потоком, OpenClaw усе одно надсилає новий текст, зберігаючи медіа як одноразову доставку. Це запобігає дублюванню голосових нотаток або файлів у каналах на кшталт Telegram, коли агент видає `MEDIA:` під час потокової передачі, а провайдер також включає його в завершену відповідь. -## Алгоритм фрагментації (нижня/верхня межі) +## Алгоритм фрагментації (нижні/верхні межі) -Блокову фрагментацію реалізує `EmbeddedBlockChunker`: +Фрагментацію блоків реалізує `EmbeddedBlockChunker`: - **Нижня межа:** не видавати, доки буфер >= `minChars` (якщо не примусово). -- **Верхня межа:** надавати перевагу розділенню до `maxChars`; якщо примусово, розділяти на `maxChars`. -- **Пріоритет розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. -- **Кодові блоки:** ніколи не розділяти всередині блоків; коли примусово на `maxChars`, закрити + знову відкрити блок, щоб Markdown залишався коректним. +- **Верхня межа:** надавати перевагу розбиттю перед `maxChars`; якщо примусово, розбивати на `maxChars`. +- **Бажаний розрив:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив. +- **Огорожі коду:** ніколи не розбивати всередині огорож; під час примусового розбиття на `maxChars` закрити + знову відкрити огорожу, щоб Markdown залишався коректним. -`maxChars` обмежується до канального `textChunkLimit`, тому ви не можете перевищити обмеження окремого каналу. +`maxChars` обмежується до `textChunkLimit` каналу, тому неможливо перевищити обмеження окремого каналу. -## Об'єднання (злиття потокових блоків) +## Об’єднання (злиття потокових блоків) -Коли блокову потокову передачу ввімкнено, OpenClaw може **об'єднувати послідовні блокові фрагменти** перед їх надсиланням. Це зменшує «спам одним рядком», водночас забезпечуючи поступовий вивід. +Коли потокову передачу блоків увімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їх надсиланням. Це зменшує «спам з одного рядка», водночас зберігаючи поступовий вивід. -- Об'єднання чекає на **паузи без активності** (`idleMs`) перед очищенням буфера. -- Буфери обмежуються `maxChars` і очищуються, якщо перевищують його. -- `minChars` не дає надсилати крихітні фрагменти, доки не накопичиться достатньо тексту (фінальне очищення завжди надсилає решту тексту). -- З'єднувач виводиться з `blockStreamingChunk.breakPreference` - (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл). -- Перевизначення каналів доступні через `*.blockStreamingCoalesce` (включно з конфігураціями для окремих облікових записів). -- Типове `minChars` для об'єднання підвищено до 1500 для Signal/Slack/Discord, якщо не перевизначено. +- Об’єднання чекає на **періоди простою** (`idleMs`) перед скиданням. +- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать його. +- `minChars` не дає надсилати крихітні фрагменти, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишковий текст). +- З’єднувач виводиться з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл). +- Перевизначення каналів доступні через `*.blockStreamingCoalesce` (зокрема конфігурації для окремих акаунтів). +- Типове значення `minChars` для об’єднання підвищено до 1500 для Signal/Slack/Discord, якщо його не перевизначено. ## Людський темп між блоками -Коли блокову потокову передачу ввімкнено, можна додати **рандомізовану паузу** між блоковими відповідями (після першого блока). Це робить відповіді з кількох бульбашок природнішими. +Коли потокову передачу блоків увімкнено, можна додати **випадкову паузу** між блоковими відповідями (після першого блоку). Це робить відповіді з кількох бульбашок природнішими. -- Конфігурація: `agents.defaults.humanDelay` (перевизначення для агента через `agents.list[].humanDelay`). +- Конфігурація: `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: "off"` (лише фінальна відповідь). +- **Передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (видавати в міру генерації). Каналам, крім Telegram, також потрібне `*.blockStreaming: true`. +- **Передати все наприкінці:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо кількома фрагментами, якщо дуже довго). +- **Без потокової передачі блоків:** `blockStreamingDefault: "off"` (лише фінальна відповідь). -**Примітка щодо каналу:** Блокова потокова передача **вимкнена, якщо** -`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати live-попередній перегляд -(`channels..streaming`) без блокових відповідей. +**Примітка щодо каналів:** Потокова передача блоків **вимкнена, якщо** +`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати потоком живий попередній перегляд (`channels..streaming`) без блокових відповідей. -Нагадування про розташування конфігурації: типові значення `blockStreaming*` розміщені в -`agents.defaults`, а не в кореневій конфігурації. +Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в кореневій конфігурації. ## Режими потокового попереднього перегляду @@ -117,78 +114,79 @@ Model output Режими: -- `off`: вимикає потоковий попередній перегляд. +- `off`: вимкнути потоковий попередній перегляд. - `partial`: один попередній перегляд, який замінюється найновішим текстом. - `block`: попередній перегляд оновлюється фрагментованими/доданими кроками. - `progress`: попередній перегляд прогресу/статусу під час генерації, фінальна відповідь після завершення. ### Відповідність каналів -| Канал | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | ---------------------- | -| Telegram | ✅ | ✅ | ✅ | відповідає `partial` | -| Discord | ✅ | ✅ | ✅ | відповідає `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | +| Канал | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | --------------------------- | +| Telegram | ✅ | ✅ | ✅ | зіставляється з `partial` | +| Discord | ✅ | ✅ | ✅ | зіставляється з `partial` | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | Лише Slack: -- `channels.slack.streaming.nativeTransport` перемикає виклики нативного API потокової передачі Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`). -- Нативна потокова передача Slack і статус треду асистента Slack потребують цільового треду відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі треду, але все ще можуть використовувати чернетки дописів попереднього перегляду Slack і редагування. +- `channels.slack.streaming.nativeTransport` перемикає нативні виклики Slack API для потокової передачі, коли `channels.slack.streaming.mode="partial"` (типово: `true`). +- Нативна потокова передача Slack і статус треду асистента Slack потребують цільового треду відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі треду, але все одно можуть використовувати чернеткові дописи попереднього перегляду Slack і редагування. Міграція застарілих ключів: -- Telegram: застарілі значення `streamMode` і скалярні/булеві значення `streaming` виявляються й мігруються шляхами doctor/сумісності конфігурації до `streaming.mode`. -- Discord: `streamMode` + булеве `streaming` автоматично мігрують до enum `streaming`. -- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булеве `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застаріле `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`. +- Telegram: застарілі значення `streamMode` і скалярні/булеві значення `streaming` виявляються та мігруються шляхами сумісності doctor/config до `streaming.mode`. +- Discord: `streamMode` + булевий `streaming` автоматично мігрують до enum `streaming`. +- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булевий `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`. ### Поведінка під час виконання Telegram: -- Використовує оновлення попереднього перегляду `sendMessage` + `editMessageText` у DM і групах/темах. -- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий близько однієї хвилини, а потім очищує попередній перегляд, щоб часова мітка Telegram відображала завершення відповіді. -- Потоковий попередній перегляд пропускається, коли блокову потокову передачу Telegram явно ввімкнено (щоб уникнути подвійної потокової передачі). +- Використовує `sendMessage` + оновлення попереднього перегляду через `editMessageText` у DM і групах/темах. +- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий приблизно одну хвилину, а потім очищає попередній перегляд, щоб мітка часу Telegram відображала завершення відповіді. +- Потоковий попередній перегляд пропускається, коли потокову передачу блоків Telegram явно увімкнено (щоб уникнути подвійної потокової передачі). - `/reasoning stream` може записувати міркування в попередній перегляд. Discord: - Використовує надсилання + редагування повідомлень попереднього перегляду. - Режим `block` використовує фрагментацію чернетки (`draftChunk`). -- Потоковий попередній перегляд пропускається, коли блокову потокову передачу Discord явно ввімкнено. -- Фінальні медіа, помилки та навантаження явних відповідей скасовують очікувані попередні перегляди без очищення нової чернетки, а потім використовують звичайну доставку. +- Потоковий попередній перегляд пропускається, коли потокову передачу блоків Discord явно увімкнено. +- Фінальні медіа, помилки та навантаження з явною відповіддю скасовують очікувані попередні перегляди без скидання нової чернетки, а потім використовують звичайну доставку. Slack: - `partial` може використовувати нативну потокову передачу Slack (`chat.startStream`/`append`/`stop`), коли вона доступна. -- `block` використовує попередні перегляди чернеток у стилі додавання. +- `block` використовує чернеткові попередні перегляди у стилі додавання. - `progress` використовує текст попереднього перегляду статусу, потім фінальну відповідь. -- DM верхнього рівня без треду відповіді використовують чернетки дописів попереднього перегляду та редагування замість нативної потокової передачі Slack. -- Нативний і чернетковий потоковий попередній перегляд пригнічують блокові відповіді для цього звернення, тому відповідь Slack передається лише одним шляхом доставки. -- Фінальні медіа/помилки та фінали прогресу не створюють одноразові повідомлення-чернетки; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, очищують очікуваний текст чернетки. +- DM верхнього рівня без треду відповіді використовують чернеткові дописи попереднього перегляду та редагування замість нативної потокової передачі Slack. +- Нативний і чернетковий потоковий попередній перегляд пригнічують блокові відповіді для цього ходу, тому відповідь Slack передається потоком лише одним шляхом доставки. +- Фінальні медіа/помилки та фінали прогресу не створюють одноразових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний чернетковий текст. Mattermost: -- Передає міркування, активність інструментів і частковий текст відповіді в один допис-чернетку попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надіслати. -- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний під час фіналізації. -- Фінальні медіа/помилки скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість очищення тимчасового допису попереднього перегляду. +- Передає думки, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надіслати. +- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний на момент фіналізації. +- Фінальні медіа/помилки скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасового допису попереднього перегляду. Matrix: -- Чернетки попереднього перегляду фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. -- Фінали лише з медіа, помилки та фінали з невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується. +- Чернеткові попередні перегляди фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду. +- Фінали лише з медіа, помилками та з невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується як видалений. ### Оновлення попереднього перегляду прогресу інструментів -Потоковий попередній перегляд також може включати оновлення **прогресу інструментів** — короткі рядки стану на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента", які з'являються в тому самому повідомленні попереднього перегляду, доки інструменти виконуються, перед фінальною відповіддю. Це підтримує візуальну активність багатоетапних звернень з інструментами, а не тишу між першим попереднім переглядом міркування та фінальною відповіддю. +Потоковий попередній перегляд також може включати оновлення **прогресу інструментів** — короткі рядки статусу на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента", які з’являються в тому самому повідомленні попереднього перегляду, доки інструменти працюють, перед фінальною відповіддю. Це підтримує візуальну активність багатоетапних ходів з інструментами, а не тишу між першим попереднім переглядом думок і фінальною відповіддю. Підтримувані поверхні: -- **Discord**, **Slack**, **Telegram** і **Matrix** типово передають прогрес інструментів у редагування live-попереднього перегляду, коли потоковий попередній перегляд активний. -- Telegram постачається з увімкненими оновленнями попереднього перегляду прогресу інструментів з `v2026.4.22`; збереження їх увімкненими підтримує цю випущену поведінку. -- **Mattermost** уже включає активність інструментів у свій єдиний допис-чернетку попереднього перегляду (див. вище). -- Редагування прогресу інструментів дотримуються активного режиму потокового попереднього перегляду; вони пропускаються, коли потоковий попередній перегляд має стан `off` або коли блокова потокова передача перебрала повідомлення. У Telegram `streaming.mode: "off"` означає лише фінальну відповідь: загальні повідомлення про прогрес також пригнічуються замість доставки як окремі повідомлення "Working...", тоді як запити на схвалення, медіанавантаження та помилки все ще маршрутизуються звичайно. -- Щоб зберегти потоковий попередній перегляд, але приховати рядки прогресу інструментів, встановіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, встановіть `streaming.mode` у `off`. +- **Discord**, **Slack**, **Telegram** і **Matrix** типово передають прогрес інструментів у редагування живого попереднього перегляду, коли потоковий попередній перегляд активний. +- 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). Приклад: @@ -207,8 +205,8 @@ Matrix: } ``` -## Пов'язане +## Пов’язане -- [Повідомлення](/uk/concepts/messages) — життєвий цикл і доставка повідомлень -- [Повторна спроба](/uk/concepts/retry) — поведінка повторних спроб у разі помилки доставки +- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлень і доставка +- [Повторна спроба](/uk/concepts/retry) — поведінка повторної спроби в разі помилки доставки - [Канали](/uk/channels) — підтримка потокової передачі для кожного каналу