From 638c57d1d222e467bc804692f1640d0cf1cb09ea Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 16:51:07 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/telegram.md | 419 ++++++++++++++++++----------------- 1 file changed, 211 insertions(+), 208 deletions(-) diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index b44df63b9..5e2907315 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,24 +1,24 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Статус підтримки, можливості та конфігурація бота Telegram +summary: Статус підтримки бота Telegram, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-04-25T12:04:22Z" + generated_at: "2026-04-25T16:48:58Z" model: gpt-5.4 provider: openai - source_hash: 24c32a83e86358afb662c9c354a1b538c90693d07dcc048eaf047dabd6822f7e + source_hash: 9509ae437c6017c966d944b6d09af65b106f78ea023174127ac900b8cdc45ede source_path: channels/telegram.md workflow: 15 --- -Готово до продакшену для бот-DM і груп через grammY. Режим long polling є типовим; режим Webhook — необов’язковий. +Готовий до продакшену для DM бота та груп через grammY. Long polling — режим за замовчуванням; режим Webhook є опціональним. - Типова політика DM для Telegram — сполучення. + Політика DM за замовчуванням для Telegram — сполучення. - + Міжканальна діагностика та сценарії відновлення. @@ -30,7 +30,7 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що хендл точно `@BotFather`). + Відкрийте Telegram і почніть чат з **@BotFather** (переконайтеся, що хендл точно `@BotFather`). Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. @@ -51,7 +51,7 @@ x-i18n: } ``` - Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише для типового облікового запису). + Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням). Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. @@ -64,26 +64,26 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення спливають через 1 годину. + Коди сполучення дійсні протягом 1 години. - Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + Додайте бота до своєї групи, а потім задайте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. -Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним варіантом через env, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису. +Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним варіантом через env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. ## Налаштування на боці Telegram - За замовчуванням Telegram-боти працюють у **Privacy Mode**, який обмежує, які повідомлення з груп вони отримують. + Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, який обмежує, які повідомлення групи вони отримують. - Якщо боту потрібно бачити всі повідомлення в групі, зробіть одне з такого: + Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. @@ -101,7 +101,7 @@ openclaw pairing approve telegram - - `/setjoingroups`, щоб дозволити/заборонити додавання в групи + - `/setjoingroups` щоб дозволити/заборонити додавання до груп - `/setprivacy` для керування видимістю в групах @@ -111,30 +111,30 @@ openclaw pairing approve telegram - `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: + `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - - `pairing` (типово) + - `pairing` (за замовчуванням) - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` підтримуються та нормалізуються. - `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config. + `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваш config містить записи allowlist у вигляді `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (best-effort; потрібен токен Telegram-бота). - Якщо ви раніше покладалися на файли allowlist у pairing-store, `openclaw doctor --fix` може відновити записи до `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (у режимі best-effort; потрібен токен бота Telegram). + Якщо ви раніше покладалися на файли allowlist зі сховища сполучення, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для потоків allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID у `allowFrom`, щоб політика доступу залишалася сталою в config (замість залежності від попередніх схвалень сполучення). + Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень сполучення). Поширена плутанина: схвалення сполучення для DM не означає, що «цей відправник авторизований всюди». - Сполучення надає доступ лише до DM. Авторизація відправників у групах і далі визначається явними allowlist у config. - Якщо ви хочете, щоб «я один раз авторизувався, і працюють і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`. + Сполучення надає доступ лише до DM. Авторизація відправника в групах, як і раніше, походить лише з явних allowlist у config. + Якщо ви хочете, щоб «я авторизувався один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`. ### Як знайти свій ID користувача Telegram Безпечніший спосіб (без стороннього бота): - 1. Напишіть своєму боту в DM. + 1. Надішліть DM своєму боту. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. @@ -149,30 +149,30 @@ curl "https://api.telegram.org/bot/getUpdates" - Разом застосовуються два механізми контролю: + Разом застосовуються два елементи керування: 1. **Які групи дозволені** (`channels.telegram.groups`) - - без config `groups`: + - немає config `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - - з `groupPolicy: "allowlist"` (типово): групи блокуються, доки ви не додасте записи до `groups` (або `"*"`) + - з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи до `groups` (або `"*"`) - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - - `allowlist` (типово) + - `allowlist` (за замовчуванням) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує резервне значення з `allowFrom`. - Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються). - Не вказуйте ID чатів Telegram group або supergroup у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправників. - Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення DM з pairing-store. - Сполучення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` на рівні групи/теми. - Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з config `allowFrom`, а не з pairing store. - Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom`, і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням використовує fail-closed `groupPolicy="allowlist"`, якщо явно не задано `channels.defaults.groupPolicy`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram повертається до `allowFrom`. + Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). + Не вказуйте ID чатів груп Telegram або супергруп у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`. + Нечислові записи ігноруються для авторизації відправника. + Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення зі сховища сполучення для DM. + Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні конкретної групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до `allowFrom` з config, а не до сховища сполучення. + Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. + Примітка про runtime: якщо `channels.telegram` повністю відсутній, типові значення runtime працюють у fail-closed режимі з `groupPolicy="allowlist"`, якщо явно не задано `channels.defaults.groupPolicy`. - Приклад: дозволити будь-якому учаснику в одній конкретній групі: + Приклад: дозволити будь-якого учасника в одній конкретній групі: ```json5 { @@ -189,7 +189,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретним користувачам в одній конкретній групі: + Приклад: дозволити лише конкретних користувачів в одній конкретній групі: ```json5 { @@ -209,20 +209,20 @@ curl "https://api.telegram.org/bot/getUpdates" Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram. - - Додавайте від’ємні ID груп Telegram або supergroup, наприклад `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, наприклад `8734062810`, у `groupAllowFrom`, коли хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг писати боту. + - Вказуйте від’ємні ID груп Telegram або супергруп, наприклад `-1001234567890`, у `channels.telegram.groups`. + - Вказуйте ID користувачів Telegram, наприклад `8734062810`, у `groupAllowFrom`, якщо хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота. + - Використовуйте `groupAllowFrom: ["*"]` лише якщо хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. - - Відповіді в групах за замовчуванням потребують згадки. + + Відповіді в групах за замовчуванням вимагають згадки. Згадка може надходити з: - нативної згадки `@botusername`, або - - шаблонів згадок у: + - шаблонів згадки в: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -231,7 +231,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для постійного збереження використовуйте config. + Вони оновлюють лише стан сесії. Для збереження використовуйте config. Приклад постійної конфігурації: @@ -249,7 +249,7 @@ curl "https://api.telegram.org/bot/getUpdates" Як отримати ID групового чату: - - перешліть повідомлення з групи в `@userinfobot` / `@getidsbot` + - перешліть повідомлення з групи до `@userinfobot` / `@getidsbot` - або прочитайте `chat.id` з `openclaw logs --follow` - або перегляньте Bot API `getUpdates` @@ -259,32 +259,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються до спільного конверта каналу з метаданими відповіді та заповнювачами медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб зберегти ізоляцію тем. -- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії, що враховують треди, і зберігає ID треду для відповідей. -- Long polling використовує grammY runner із послідовністю на рівні чату/треду. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`. -- Long polling захищений усередині кожного процесу gateway, тому лише один активний poller може одночасно використовувати токен бота. Якщо ви все ще бачите конфлікти `getUpdates` 409, той самий токен, імовірно, використовує інший gateway OpenClaw, скрипт або зовнішній poller. -- Перезапуски watchdog для long polling спрацьовують після 120 секунд без завершеної активності `getUpdates` за замовчуванням. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні й далі трапляються хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). +- Маршрутизація детермінована: вхідні відповіді Telegram повертаються назад у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа. +- Групові сесії ізольовані за ID групи. Для тем форуму додається `:topic:`, щоб теми залишалися ізольованими. +- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесії та зберігає ID треду для відповідей. +- Long polling використовує grammY runner з послідовністю на рівні чату/треду. Загальна паралельність sink runner використовує `agents.defaults.maxConcurrent`. +- Long polling захищено всередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller. +- Перезапуски watchdog для long polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання polling під час тривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення на рівні облікового запису. +- Telegram Bot API не підтримує квитанції про прочитання (`sendReadReceipts` не застосовується). -## Довідка щодо можливостей +## Довідник функцій - - OpenClaw може транслювати часткові відповіді в реальному часі: + + OpenClaw може передавати часткові відповіді в реальному часі: - - особисті чати: повідомлення попереднього перегляду + `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` керує тим, чи перевикористовують оновлення інструментів/прогресу те саме відредаговане повідомлення попереднього перегляду (типово: `true`, коли активний preview streaming) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх до `channels.telegram.streaming.mode` + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний потоковий попередній перегляд) + - виявляються застарілі `channels.telegram.streamMode` і булеві значення `streaming`; виконайте `openclaw doctor --fix`, щоб мігрувати їх у `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Working...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або зведення патчів. У Telegram вони ввімкнені за замовчуванням, щоб відповідати випущеній поведінці OpenClaw, починаючи з `v2026.4.22` і новіше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення плану або підсумки патчів. Telegram тримає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw, починаючи з `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -301,18 +301,18 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути тільки рядки стану прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів. Для відповідей лише з текстом: - DM: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення) - група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення) - Для складних відповідей (наприклад, з медіавкладеннями) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, з медіаконтентом) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Preview streaming відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного стримінгу. + Потоковий попередній перегляд відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі. - Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично використовує резервний варіант `sendMessage` + `editMessageText`. + Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. Потік reasoning лише для Telegram: @@ -325,17 +325,17 @@ curl "https://api.telegram.org/bot/getUpdates" Вихідний текст використовує Telegram `parse_mode: "HTML"`. - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram. + - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу в Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. - Попередній перегляд посилань увімкнено за замовчуванням і його можна вимкнути за допомогою `channels.telegram.linkPreview: false`. + Попередній перегляд посилань увімкнено за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`. Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Типові значення для нативних команд: + Типові значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram @@ -346,7 +346,7 @@ curl "https://api.telegram.org/bot/getUpdates" channels: { telegram: { customCommands: [ - { command: "backup", description: "Git-резервна копія" }, + { command: "backup", description: "Резервне копіювання Git" }, { command: "generate", description: "Створити зображення" }, ], }, @@ -356,7 +356,7 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (прибирається початковий `/`, перетворюються на нижній регістр) + - імена нормалізуються (видаляється початковий `/`, нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - користувацькі команди не можуть перевизначати нативні команди - конфлікти/дублікати пропускаються та логуються @@ -364,30 +364,30 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично - - команди Plugin/Skills можуть і далі працювати при ручному введенні, навіть якщо їх не показано в меню Telegram + - команди Plugin/Skills все одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin все ще можуть реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані буде видалено. Користувацькі команди/команди Plugin все ще можуть реєструватися, якщо це налаштовано. - Поширені збої налаштування: + Поширені збої під час налаштування: - - `setMyCommands failed` із `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - `setMyCommands failed` із помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковано. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. + - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-запити до `api.telegram.org` заблоковані. - ### Команди сполучення пристроїв (Plugin `device-pair`) + ### Команди сполучення пристрою (Plugin `device-pair`) Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список запитів, що очікують (зокрема роль/області дії) + 3. `/pair pending` показує список очікуваних запитів (зокрема роль/scopes) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один запит, що очікує + - `/pair approve`, коли є лише один запит в очікуванні - `/pair approve latest` для найновішого - Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен primary node на `scopes: []`; будь-який переданий operator token залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-областей мають префікс ролі, тому цей allowlist operator задовольняє лише operator-запити; ролям, що не є operator, усе ще потрібні області дії під власним префіксом ролі. + Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен primary Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope використовують префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, як і раніше потребують scopes під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад роль/області дії/публічний ключ), попередній запит, що очікує, заміщується, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. + Якщо пристрій повторює спробу зі зміненими даними auth (наприклад роль/scopes/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -408,7 +408,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Перевизначення для окремого облікового запису: + Перевизначення на рівні облікового запису: ```json5 { @@ -432,9 +432,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `dm` - `group` - `all` - - `allowlist` (типово) + - `allowlist` (за замовчуванням) - Застарілий запис `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. Приклад дії повідомлення: @@ -443,13 +443,13 @@ curl "https://api.telegram.org/bot/getUpdates" action: "send", channel: "telegram", to: "123456789", - message: "Choose an option:", + message: "Виберіть варіант:", buttons: [ [ - { text: "Yes", callback_data: "yes" }, - { text: "No", callback_data: "no" }, + { text: "Так", callback_data: "yes" }, + { text: "Ні", callback_data: "no" }, ], - [{ text: "Cancel", callback_data: "cancel" }], + [{ text: "Скасувати", callback_data: "cancel" }], ], } ``` @@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Дії інструментів Telegram включають: - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) @@ -468,44 +468,44 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage` (`chatId`, `messageId`, `content`) - `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` (типово: вимкнено) + - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` зараз увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання в runtime використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час runtime використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги гілок відповідей у згенерованому виводі: + + Telegram підтримує явні теги тредингу відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення-тригер + - `[[reply_to_current]]` відповідає на повідомлення, яке ініціювало дію - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: - - `off` (типово) + - `off` (за замовчуванням) - `first` - `all` - Примітка: `off` вимикає неявне створення гілок відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + Примітка: `off` вимикає неявний трединг відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - Супергрупи форумів: + Супергрупи форуму: - ключі сесій тем додають `:topic:` - відповіді та індикатор набору тексту спрямовуються в тред теми - - шлях конфігурації теми: + - шлях config теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): @@ -513,10 +513,10 @@ curl "https://api.telegram.org/bot/getUpdates" - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - дії індикатора набору тексту все одно включають `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо не перевизначені (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + Успадкування тем: записи тем успадковують налаштування групи, якщо не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` належить лише темі й не успадковується з типових значень групи. - **Маршрутизація агентів для окремих тем**: кожна тема може маршрутизуватися до іншого агента, якщо задати `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агентів для окремих тем**: кожна тема може маршрутизуватися до іншого агента через `agentId` у config теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад: ```json5 { @@ -527,7 +527,7 @@ curl "https://api.telegram.org/bot/getUpdates" topics: { "1": { agentId: "main" }, // Загальна тема → агент main "3": { agentId: "zu" }, // Тема розробки → агент zu - "5": { agentId: "coder" } // Рев’ю коду → агент coder + "5": { agentId: "coder" } // Перевірка коду → агент coder } } } @@ -536,23 +536,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Тоді кожна тема матиме власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійна прив’язка тем ACP**: теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID теми з кваліфікатором, наприклад `-1001234567890:topic:42`). Наразі область дії обмежена темами форумів у group/supergroup. Див. [ACP Agents](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії harness ACP через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з кваліфікатором теми, наприклад `-1001234567890:topic:42`). Наразі це обмежено темами форуму в групах/супергрупах. Див. [ACP Agents](/uk/tools/acp-agents). - **Запуск ACP, прив’язаний до треду, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Прив’язане до треду створення ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в самій темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесії, що враховують треди. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням треду. ### Аудіоповідомлення - Telegram розрізняє голосові нотатки та аудіофайли. + Telegram розрізняє голосові повідомлення та аудіофайли. - - типово: поведінка як для аудіофайлу - - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку + - за замовчуванням: поведінка аудіофайлу + - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення + - вхідні транскрипти голосових повідомлень оформлюються в контексті агента як машинно згенерований, + недовірений текст; виявлення згадок усе одно використовує сирий + транскрипт, тож голосові повідомлення з обмеженням за згадкою продовжують працювати. Приклад дії повідомлення: @@ -588,7 +591,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (заповнювач ``) + - статичний WEBP: завантажується та обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -606,7 +609,7 @@ curl "https://api.telegram.org/bot/getUpdates" Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити кількість повторних викликів vision. - Увімкнення дій зі стікерами: + Увімкніть дії зі стікерами: ```json5 { @@ -649,26 +652,26 @@ curl "https://api.telegram.org/bot/getUpdates" Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт: - - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` + - `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 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 (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - Telegram не надає ID тредів в оновленнях реакцій. - - групи нефорумного типу маршрутизуються до сесії групового чату - - групи форумного типу маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - нефорумні групи маршрутизуються до сесії групового чату + - групи форуму маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для polling/Webhook автоматично включають `message_reaction`. + `allowed_updates` для polling/webhook автоматично включають `message_reaction`. - + `ackReaction` надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: @@ -676,22 +679,22 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний варіант — емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний варіант через емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує емодзі Unicode (наприклад, "👀"). + - Telegram очікує Unicode-емодзі (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - - Запис конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`). + + Записи config каналу увімкнені за замовчуванням (`configWrites !== false`). Записи, ініційовані Telegram, включають: - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потрібно, щоб команди були ввімкнені) + - `/config set` і `/config unset` (потрібне ввімкнення команд) Вимкнення: @@ -707,38 +710,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`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захист запитів, секретний токен Telegram і JSON-тіло перед тим, як повернути `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі lane бота на рівні чату/теми, що й у long polling, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим Webhook перевіряє захисні умови запиту, секретний токен Telegram і JSON-тіло перед тим, як повернути `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі бот-лінії на рівні чату/теми, що й long polling, тож повільні ходи агента не затримують ACK доставки від Telegram. - - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. - - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, використовується типове значення grammY). - - Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. - - Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає її. - - Додатковий контекст reply/quote/forward наразі передається як отримано. - - Telegram allowlist переважно обмежують те, хто може запускати агента, а не є повноцінною межею редагування додаткового контексту. - - Керування історією DM: + - значення за замовчуванням для `channels.telegram.textChunkLimit` — 4000. + - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram. + - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). + - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. + - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає її. + - додатковий контекст reply/quote/forward наразі передається як отримано. + - allowlist Telegram насамперед обмежують те, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - елементи керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. + - config `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. - Ціллю CLI для надсилання може бути числовий ID чату або ім’я користувача: + Ціль надсилання CLI може бути числовим ID чату або іменем користувача: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Poll у Telegram використовують `openclaw message poll` і підтримують теми форумів: + Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -748,55 +751,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Прапорці poll лише для Telegram: + Прапорці опитувань лише для Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) - Надсилання в Telegram також підтримує: + Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для вбудованих клавіатур, якщо це дозволяє `channels.telegram.capabilities.inlineButtons` - - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, якщо бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа + - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons` + - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті + - `--force-document`, щоб надсилати вихідні зображення та GIF як документи, а не як стиснуті фото чи завантаження анімованих медіа - Контроль доступу для дій: + Керування доступом до дій: - - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема poll - - `channels.telegram.actions.poll=false` вимикає створення poll у Telegram, залишаючи звичайне надсилання ввімкненим + - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання увімкненими - - Telegram підтримує погодження exec у DM погоджувачів і за потреби може публікувати запити у вихідному чаті або темі. Погоджувачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує підтвердження exec у DM затверджувачів і за потреби може публікувати запити у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. - Шлях конфігурації: + Шлях config: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного погоджувача) - - `channels.telegram.execApprovals.approvers` (використовує числові ID власника з `allowFrom` / `defaultTo` як резервний варіант) - - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного затверджувача) + - `channels.telegram.execApprovals.approvers` (повертається до числових ID власників із `allowFrom` / `defaultTo`) + - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` - `agentFilter`, `sessionFilter` - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на погодження і подальшого повідомлення. За замовчуванням погодження exec спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на підтвердження і подальшої взаємодії. За замовчуванням термін дії підтверджень exec спливає через 30 хвилин. - Вбудовані кнопки погодження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID погоджень із префіксом `plugin:` визначаються через погодження Plugin; інші спочатку визначаються через погодження exec. + Вбудовані кнопки підтвердження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` розв’язуються через підтвердження Plugin; інші спочатку розв’язуються через підтвердження exec. - Див. [Погодження exec](/uk/tools/exec-approvals). + Див. [Підтвердження exec](/uk/tools/exec-approvals). -## Керування відповідями на помилки +## Елементи керування відповідями на помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приглушити його. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку керують два ключі config: | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приглушує відповіді з помилками. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в одному чаті. Запобігає спаму помилками під час збоїв. | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді з помилками. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів конфігурації Telegram). +Підтримуються перевизначення на рівні облікового запису, групи та теми (те саме успадкування, що й для інших ключів config Telegram). ```json5 { @@ -806,7 +809,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ errorCooldownMs: 120000, groups: { "-1001234567890": { - errorPolicy: "silent", // приглушити помилки в цій групі + errorPolicy: "silent", // придушити помилки в цій групі }, }, }, @@ -817,42 +820,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Усунення проблем - + - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - потім видаліть бота й додайте його знову до групи - `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` неможливо перевірити на членство через probe. - - швидка перевірка сесії: `/activation always`. + - `openclaw channels status --probe` може перевіряти явні числові ID груп; шаблон `"*"` не можна перевірити через membership-probe. + - швидкий тест сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути в списку (або має бути `"*"`) - - перевірте, що бот є учасником групи + - коли існує `channels.telegram.groups`, група має бути вказана в списку (або має міститися `"*"`) + - перевірте членство бота в групі - перегляньте логи: `openclaw logs --follow` для причин пропуску - + - авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`) - - авторизація команд усе ще застосовується, навіть коли політика групи `open` - - `setMyCommands failed` із `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню містить забагато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню - - `setMyCommands failed` із помилками network/fetch зазвичай вказує на проблеми досяжності DNS/HTTPS до `api.telegram.org` + - авторизація команд усе одно застосовується, навіть коли політика групи `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню + - `setMyCommands failed` з помилками мережі/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org` - - Node 22+ + користувацький fetch/proxy можуть викликати негайне переривання, якщо типи AbortSignal не збігаються. - - На деяких хостах `api.telegram.org` спочатку визначається в IPv6; несправний вихід через IPv6 може спричиняти переривчасті збої Telegram API. - - Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці спроби як відновлювані мережеві помилки. - - Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної активності long-poll за замовчуванням. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довгі виклики `getUpdates` працюють нормально, але ваш хост усе одно повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`. - - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ + custom fetch/proxy можуть спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються. + - Деякі хости спочатку резолвлять `api.telegram.org` в IPv6; несправний вихід через IPv6 може спричиняти періодичні збої Telegram API. + - Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює такі спроби як відновлювані мережеві помилки. + - Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише коли довготривалі виклики `getUpdates` є справними, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`. + - На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -860,8 +863,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - У Node 22+ типові значення — `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово виберіть сімейство адрес: + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. + - Якщо ваш хост — це WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -870,11 +873,11 @@ channels: autoSelectFamily: false ``` - - Відповіді в діапазоні тестування RFC 2544 (`198.18.0.0/15`) уже дозволені + - Відповіді з діапазону RFC 2544 benchmark (`198.18.0.0/15`) уже дозволені за замовчуванням для завантаження медіа Telegram. Якщо довірений fake-IP або transparent proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете - увімкнути обхід лише для Telegram: + приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете + свідомо ввімкнути обхід лише для Telegram: ```yaml channels: @@ -883,25 +886,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Той самий opt-in доступний для окремого облікового запису в + - Те саме явне ввімкнення доступне на рівні облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште + - Якщо ваш proxy резолвить медіахости Telegram у `198.18.x.x`, спочатку залиште небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяє - діапазон тестування RFC 2544. + діапазон RFC 2544 benchmark. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист - від SSRF у медіа Telegram. Використовуйте це лише в довірених середовищах proxy, - якими керує оператор, таких як Clash, Mihomo або Surge fake-IP routing, коли вони - синтезують приватні або спеціальні адреси поза діапазоном тестування RFC 2544. - Для звичайного публічного доступу до Telegram через інтернет залишайте це вимкненим. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram + від SSRF для медіа. Використовуйте це лише для довірених середовищ proxy, + якими керує оператор, наприклад Clash, Mihomo або Surge з маршрутизацією fake-IP, коли вони + синтезують приватні або special-use відповіді поза межами + діапазону RFC 2544 benchmark. Залишайте це вимкненим для звичайного публічного доступу до Telegram через інтернет. - - Перевизначення через змінні середовища (тимчасові): + - Перевизначення через середовище (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірка відповідей DNS: ```bash dig +short api.telegram.org A @@ -911,23 +914,23 @@ dig +short api.telegram.org AAAA -Більше допомоги: [Усунення проблем каналів](/uk/channels/troubleshooting). +Додаткова допомога: [Усунення проблем каналу](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + -- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlink відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) -- погодження exec: `execApprovals`, `accounts.*.execApprovals` +- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symbolic links відхиляються) +- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`) +- підтвердження exec: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` -- треди/відповіді: `replyToMode` -- стримінг: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- трединг/відповіді: `replyToMode` +- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -936,14 +939,14 @@ dig +short api.telegram.org AAAA -Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явним чином визначити типову маршрутизацію. Інакше OpenClaw використовує перший нормалізований ID облікового запису як резервний варіант, а `openclaw doctor` виводить попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, і `openclaw doctor` видає попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. -## Пов’язані +## Пов’язане - Зіставте користувача Telegram із gateway. + Сполучіть користувача Telegram із gateway. Поведінка allowlist для груп і тем. @@ -955,7 +958,7 @@ dig +short api.telegram.org AAAA Модель загроз і посилення захисту. - Зіставте групи й теми з агентами. + Зіставляйте групи й теми з агентами. Міжканальна діагностика.