diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 574d11054..d3811f289 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Статус підтримки бота Telegram, можливості та конфігурація +summary: Стан підтримки бота Telegram, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-05-03T15:47:48Z" + generated_at: "2026-05-03T15:57:49Z" model: gpt-5.5 provider: openai - source_hash: 5f234bc5f33eacbed3bfdc9d60285ea22ce4747f727cdb13863732238470a62d + source_hash: 730b26df661d5faacdc393b1a017ac36ee38371b9cee6a6dffe8b627566ce2e2 source_path: channels/telegram.md workflow: 16 --- -Готово для продакшену для особистих повідомлень ботам і груп через grammY. Long polling є режимом за замовчуванням; режим webhook є необов’язковим. +Готовий для production-використання в DM ботів і групах через grammY. Режим довгого опитування є стандартним; режим Webhook необов’язковий. - Політика особистих повідомлень за замовчуванням для Telegram — сполучення. + Стандартна політика DM для Telegram — сполучення. - Діагностика між каналами та інструкції з відновлення. + Міжканальна діагностика та інструкції з відновлення. Повні шаблони та приклади конфігурації каналів. @@ -30,13 +30,13 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). + Відкрийте Telegram і напишіть **@BotFather** (переконайтеся, що handle точно `@BotFather`). Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. - + ```json5 { @@ -51,12 +51,12 @@ x-i18n: } ``` - Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис). Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. - + ```bash openclaw gateway @@ -74,21 +74,21 @@ openclaw pairing approve telegram -Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису. ## Налаштування на боці Telegram - - Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. + + Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує групові повідомлення, які вони отримують. - Якщо бот має бачити всі групові повідомлення, зробіть одне з такого: + Якщо бот має бачити всі групові повідомлення, зробіть одне з двох: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. + Під час перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. @@ -110,35 +110,35 @@ openclaw pairing approve telegram ## Контроль доступу та активація - - `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: + + `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - `pairing` (за замовчуванням) - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`) - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` із `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із суворо обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `dmPolicy: "open"` з `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає username бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `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` блокує всі DM і відхиляється перевіркою config. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися й ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токена бота Telegram). + Якщо ви оновилися і ваш config містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (найкраща спроба; потребує токена бота Telegram). Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення). + Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була довговічною в config (замість залежності від попередніх схвалень сполучення). - Поширена плутанина: схвалення сполучення в особистих повідомленнях не означає "цей відправник авторизований усюди". - Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. - Авторизація відправника в групі все одно походить із явних allowlists у конфігурації. - Якщо ви хочете "я авторизований один раз, і працюють як особисті повідомлення, так і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. + Поширена плутанина: схвалення сполучення DM не означає «цей відправник авторизований усюди». + Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. + Авторизація відправника в групі все одно походить з явних config allowlist. + Якщо ви хочете «мене авторизовано один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Напишіть своєму боту в особисті повідомлення. + 1. Напишіть своєму боту в DM. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. @@ -152,8 +152,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Два елементи керування застосовуються разом: + + Два засоби керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає config `groups`: @@ -161,22 +161,22 @@ curl "https://api.telegram.org/bot/getUpdates" - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - `groups` налаштовано: діє як allowlist (явні ID або `"*"`) - 2. **Яким відправникам дозволено в групах** (`channels.telegram.groupPolicy`) + 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (за замовчуванням) - `disabled` `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень для особистих повідомлень. - Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. + Нечислові записи ігноруються для авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM. + Сполучення залишається лише для DM. Для груп задайте `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` не задано явно. - Приклад: дозволити будь-якого учасника в одній конкретній групі: + Приклад: дозволити будь-якому учаснику в одній конкретній групі: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретних користувачів в одній конкретній групі: + Приклад: дозволити лише конкретним користувачам в одній конкретній групі: ```json5 { @@ -211,11 +211,11 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. + Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram. - - Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг звертатися до бота. @@ -224,21 +224,21 @@ curl "https://api.telegram.org/bot/getUpdates" Групові відповіді за замовчуванням потребують згадки. - Згадка може походити з: + Згадка може надходити з: - нативної згадки `@botusername`, або - - шаблонів згадок у: + - шаблонів згадки в: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд на рівні сесії: + Перемикачі команд рівня сесії: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для збереження використовуйте config. + Вони оновлюють лише стан сесії. Використовуйте config для збереження. - Приклад сталої конфігурації: + Приклад постійного config: ```json5 { @@ -256,7 +256,7 @@ curl "https://api.telegram.org/bot/getUpdates" - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` - або прочитайте `chat.id` з `openclaw logs --follow` - - або перегляньте Bot API `getUpdates` + - або перевірте Bot API `getUpdates` @@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа. +- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та 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`; підтримуються перевизначення для окремих облікових записів. +- DM-повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням тримає DM у пласкій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідний config теми, коли ви навмисно хочете ізоляцію сесій тем DM. +- Довге опитування використовує runner grammY з послідовністю для кожного чату/потоку. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший OpenClaw gateway, script або зовнішній poller, імовірно, використовує той самий токен. +- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через stall опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для кожного облікового запису. - Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - - прямі чати: повідомлення preview + `editMessageText` - - групи/теми: повідомлення preview + `editMessageText` + - прямі чати: повідомлення попереднього перегляду + `editMessageText` + - групи/теми: повідомлення попереднього перегляду + `editMessageText` Вимога: - - `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`) + - `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` + - `streaming.preview.toolProgress` керує тим, чи оновлення tool/progress повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли preview streaming активний) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` - Оновлення preview для прогресу інструментів — це короткі рядки "Працюємо...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати поведінці OpenClaw, випущеній у `v2026.4.22` і пізніше. Щоб зберегти редагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду перебігу роботи інструментів — це короткі рядки «Working...», які показуються під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати поведінці OpenClaw, випущеній у `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки перебігу роботи інструментів, задайте: ```json { @@ -306,47 +306,48 @@ 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`, щоб прийняти цей компроміс. + Відповіді на вибрані цитати в Telegram є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний шлях відповіді на цитату Telegram замість редагування прев’ю відповіді, тому `streaming.preview.toolProgress` не може показати короткі рядки "Working..." для цього звернення. Відповіді на поточне повідомлення без тексту вибраної цитати все ще зберігають потокове прев’ю. Встановіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді на цитати, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс. Для текстових відповідей: - - короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, тому видима часова позначка Telegram відображає час завершення, а не час створення попереднього перегляду + - короткі прев’ю в DM/групі/темі: OpenClaw зберігає те саме повідомлення прев’ю і виконує фінальне редагування на місці, якщо після появи прев’ю не було надіслано видиме повідомлення, що не є прев’ю + - прев’ю, після яких іде видимий вивід, що не є прев’ю: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення й очищає старіше прев’ю, тож фінальна відповідь з’являється після проміжного виводу + - прев’ю, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає прев’ю, тож видима позначка часу Telegram відображає час завершення, а не час створення прев’ю - Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення прев’ю. - Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потокове прев’ю відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік прев’ю, щоб уникнути подвійного потокового передавання. - Потік міркувань лише для Telegram: + Потік міркувань тільки для Telegram: - - `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерації + - `/reasoning stream` надсилає міркування в живе прев’ю під час генерації - фінальна відповідь надсилається без тексту міркувань - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. - - Необроблений HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як простий текст. + - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram. + - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. - Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. + Прев’ю посилань увімкнені за замовчуванням, їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`. + + Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`. - Типові значення нативних команд: + Стандартні значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте користувацькі записи меню команд: + Додайте власні записи меню команд: ```json5 { @@ -363,47 +364,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - назви нормалізуються (прибирається початковий `/`, переводяться в нижній регістр) + - назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - користувацькі команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються й логуються + - власні команди не можуть перевизначати нативні команди + - конфлікти/дублікати пропускаються і записуються в журнал Примітки: - - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - - команди Plugin/Skills можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram + - власні команди є лише записами меню; вони не реалізують поведінку автоматично + - команди plugin/skill можуть працювати під час введення, навіть якщо не показані в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть і далі реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні/plugin-команди все ще можуть реєструватися, якщо налаштовані. - Поширені збої налаштування: + Поширені помилки налаштування: - - `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` заблоковано. + - `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` було встановлено на повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється перед опитуванням, тому це не повідомляється як помилка очищення Webhook. + - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. - ### Команди сполучення пристрою (Plugin `device-pair`) + ### Команди сполучення пристрою (`device-pair` plugin) - Коли Plugin `device-pair` встановлено: + Коли встановлено `device-pair` plugin: 1. `/pair` генерує код налаштування - 2. вставте код у застосунок iOS - 3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями дії) + 2. вставте код в iOS app + 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 { @@ -443,7 +444,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. Приклад дії повідомлення: @@ -463,7 +464,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Натискання зворотних викликів передаються агенту як текст: + Натискання callback передаються агенту як текст: `callback_data: ` @@ -471,15 +472,15 @@ curl "https://api.telegram.org/bot/getUpdates" Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Керування обмеженнями: + Елементи керування доступом: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -487,16 +488,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують довільне повторне розв’язання SecretRef для кожного надсилання. + Надсилання під час виконання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ситуативне повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги гілок відповідей у згенерованому виводі: + + Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що запустило обробку + - `[[reply_to_current]]` відповідає на повідомлення, що запустило дію - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -505,29 +506,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли гілки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до простої відповіді, якщо Telegram відхиляє цитату. + Коли ланцюжки відповідей увімкнено і оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні гілки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. + Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. - - Форумні супергрупи: + + Супергрупи форуму: - - ключі сеансів теми додають `:topic:` - - відповіді та індикатор набору тексту спрямовуються в гілку теми - - шлях конфігурації теми: + - ключі сесій теми додають `:topic:` + - відповіді й індикатор набору тексту спрямовуються в ланцюжок теми + - шлях config теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії набору тексту все одно містять `message_thread_id` + - надсилання повідомлень опускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії набору тексту все ще включають `message_thread_id` - Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` застосовується лише до теми й не успадковується з типових значень групи. + Наслідування теми: записи теми наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` належить лише темі й не наслідується з типових значень групи. - **Маршрутизація агента для окремої теми**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад: + **Маршрутизація агента для кожної теми**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -547,13 +548,13 @@ 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"` та ID із кваліфікатором теми, наприклад `-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). - **Створення thread-bound ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються безпосередньо туди. OpenClaw закріплює підтвердження створення в темі. Потребує, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). + **Thread-bound ACP spawn із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження spawn у темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишався ввімкненим (за замовчуванням: `true`). - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають DM-маршрутизацію і метадані відповіді в плоских сеансах; вони використовують ключі сеансів з урахуванням гілок лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня для типового значення облікового запису або `direct..threadReplies` для одного DM. + Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді у плоских сесіях; вони використовують ключі сесій з урахуванням ланцюжків лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідний config теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня як типове значення облікового запису або `direct..threadReplies` для одного DM. @@ -564,9 +565,9 @@ curl "https://api.telegram.org/bot/getUpdates" - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, - ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий - транскрипт, тому голосові повідомлення з обмеженням за згадкою й далі працюють. + - транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований, + недовірений текст; виявлення згадок усе ще використовує сирий + транскрипт, тому голосові повідомлення з вимогою згадки продовжують працювати. Приклад дії повідомлення: @@ -602,7 +603,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (placeholder ``) + - статичний WEBP: завантажується й обробляється (плейсхолдер ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -618,7 +619,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики розпізнавання зображень. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision. Увімкнути дії зі стікерами: @@ -658,10 +659,10 @@ curl "https://api.telegram.org/bot/getUpdates" - + Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень). - Коли ввімкнено, OpenClaw додає в чергу системні події на кшталт: + Якщо ввімкнено, OpenClaw ставить у чергу системні події на кшталт: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -673,16 +674,16 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). - - Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає thread IDs в оновленнях реакцій. - - групи без форумів спрямовуються до сесії групового чату - - групи-форуми спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ID потоків в оновленнях реакцій. + - нефорумні групи маршрутизуються до сесії групового чату + - форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної вихідної теми `allowed_updates` для polling/webhook автоматично включає `message_reaction`. - + `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: @@ -695,17 +696,17 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - Telegram очікує unicode emoji (наприклад, "👀"). - - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. - + Записи конфігурації каналу ввімкнені типово (`configWrites !== false`). - Записи, ініційовані Telegram, включають: + Записи, спричинені Telegram, включають: - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потрібне ввімкнення команди) + - `/config set` і `/config unset` (потребує ввімкнення команд) Вимкнути: @@ -721,38 +722,38 @@ curl "https://api.telegram.org/bot/getUpdates" - - Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; додатково `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). + + Типовий режим — long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON body перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі per-chat/per-topic bot lanes, що й long polling, тому повільні ходи агента не затримують delivery ACK Telegram. + Режим webhook перевіряє захист запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі 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-секундного 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 переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти бота обмежують налаштовані значення, нижчі за 60-секундний guard для вихідних text/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` застосовується до helper-ів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений safe-send retry для збоїв Telegram pre-connect, але не повторює неоднозначні post-send network envelopes, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до helpers надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений safe-send retry для pre-connect збоїв Telegram, але не повторює неоднозначні post-send мережеві envelopes, які можуть дублювати видимі повідомлення. - Ціль надсилання CLI може бути числовим chat ID або username: + Ціль надсилання CLI може бути числовим ID чату або username: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Опитування Telegram використовують `openclaw message poll` і підтримують теми форумів: + Опитування Telegram використовують `openclaw message poll` і підтримують форумні теми: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -767,36 +768,36 @@ 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` для inline keyboards, коли це дозволяє `channels.telegram.capabilities.inlineButtons` - - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media + - `--presentation` з блоками `buttons` для inline keyboards, коли `channels.telegram.capabilities.inlineButtons` це дозволяє + - `--pin` або `--delivery '{"pin":true}'` для запиту pinned delivery, коли бот може pin у цьому чаті + - `--force-document` для надсилання вихідних зображень і GIF як документів замість стисненого photo або animated-media uploads Обмеження дій: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями - - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими - - Telegram підтримує exec approvals в DM approver-ів і може додатково публікувати prompts у початковому чаті або темі. Approver-и мають бути числовими Telegram user IDs. + + Telegram підтримує exec approvals у DM затверджувачів і може додатково публікувати prompts у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного approver-а) - - `channels.telegram.execApprovals.approvers` (fallback до числових owner IDs із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача) + - `channels.telegram.execApprovals.approvers` (fallback до числових owner ID з `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver-ом. Перше схвалене pairing DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе одно працює без дублювання IDs у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver. Перше схвалене DM pairing ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє в тему форуму, OpenClaw зберігає тему для prompt схвалення і follow-up. Exec approvals типово спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для approval prompt і подальшого повідомлення. Exec approvals типово спливають через 30 хвилин. - Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Approval IDs із префіксом `plugin:` визначаються через plugin approvals; інші спершу визначаються через exec approvals. + Inline approval buttons також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Approval IDs з префіксом `plugin:` визначаються через plugin approvals; інші спершу визначаються через exec approvals. Див. [Exec approvals](/uk/tools/exec-approvals). @@ -805,14 +806,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або provider-а, 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 { @@ -833,56 +834,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Усунення несправностей - + - - Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість. + - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові group IDs; wildcard `"*"` не можна перевірити на membership. + - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - швидкий тест сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`) - - перевірте membership бота в групі + - коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`) + - перевірте членство бота в групі - перегляньте логи: `openclaw logs --follow` для причин пропуску - + - - авторизуйте вашу 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` + - авторизуйте свою ідентичність відправника (pairing і/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи — `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menus + - startup виклики `deleteMyCommands` / `setMyCommands` і typing виклики `sendChatAction` обмежені та повторюються один раз через transport fallback Telegram у разі timeout запиту. Постійні network/fetch помилки зазвичай вказують на проблеми досяжності DNS/HTTPS до `api.telegram.org` - + - - `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. + - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота. + - Повторно скопіюйте або згенеруйте заново токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. + - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "Webhook не існує" лише відкладе ту саму помилку поганого токена до пізніших викликів API. - + - - Node 22+ + власний fetch/proxy може спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки. - - Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, щоб runner не потребував другого `getMe` перед першим `getUpdates`. - - Якщо `deleteWebhook` завершується збоєм через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до long polling замість ще одного контрольного виклику перед опитуванням. Все ще активний webhook проявляється як конфлікт `getUpdates`; після цього OpenClaw перебудовує транспорт Telegram і повторює очищення webhook. - - Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення, нижчі за запобіжники вихідних запитів і запитів `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці запобіжники. - - Якщо журнали містять `Polling stall detected`, OpenClaw за замовчуванням перезапускає опитування і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll. - - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис з опитуванням не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис із webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність транспорту опитування застаріла. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли тривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або вихідним TLS між хостом і `api.telegram.org`. - - Telegram також враховує змінні середовища 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`: + - 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`: ```yaml channels: @@ -890,8 +891,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок DNS-результатів Telegram враховує спершу `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім стандарт процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо жодне не застосовується, Node 22+ повертається до `ipv4first`. - - Якщо ваш хост є WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (окрім WSL2). Порядок результатів DNS для Telegram враховує спершу `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім типове значення процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо жодне не застосовується, Node 22+ повертається до `ipv4first`. + - Якщо ваш хост є WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -900,10 +901,10 @@ channels: autoSelectFamily: false ``` - - Відповіді з діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені + - Відповіді діапазону для бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або - прозорий proxy переписує `api.telegram.org` на іншу - приватну/внутрішню/спеціальну адресу під час завантаження медіа, ви можете + прозорий proxy переписує `api.telegram.org` на якусь іншу + приватну/внутрішню/спеціального використання адресу під час завантаження медіа, ви можете увімкнути обхід лише для Telegram: ```yaml @@ -913,14 +914,18 @@ 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` послаблює захисти SSRF для медіа Telegram. Використовуйте це лише в довірених, контрольованих оператором середовищах proxy, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони синтезують приватні чи спеціальні відповіді поза діапазоном RFC 2544 для бенчмаркінгу. Залишайте це вимкненим для звичайного доступу Telegram через публічний інтернет. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює SSRF-захисти + медіа Telegram. Використовуйте це лише для довірених середовищ proxy, + керованих оператором, як-от Clash, Mihomo або маршрутизація fake-IP Surge, коли вони + синтезують приватні або спеціального використання відповіді поза діапазоном бенчмарків + RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. - Перевизначення середовища (тимчасові): @@ -937,24 +942,24 @@ dig +short api.telegram.org AAAA -Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting). +Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) -- підтвердження exec: `execApprovals`, `accounts.*.execApprovals` -- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` +- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) +- схвалення exec: `execApprovals`, `accounts.*.execApprovals` +- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` -- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` +- потокова передача: `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 +968,7 @@ dig +short api.telegram.org AAAA -Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити стандартну маршрутизацію явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане @@ -973,7 +978,7 @@ dig +short api.telegram.org AAAA Сполучіть користувача Telegram із Gateway. - Поведінка allowlist для груп і тем. + Поведінка списку дозволів для груп і тем. Маршрутизуйте вхідні повідомлення до агентів. @@ -985,6 +990,6 @@ dig +short api.telegram.org AAAA Зіставляйте групи й теми з агентами. - Діагностика між каналами. + Міжканальна діагностика.