From dafe7835a4dc787d463de41b209bea8dc6b1bd81 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 15:28:17 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/telegram.md | 448 +++++++++++++++++------------------ 1 file changed, 224 insertions(+), 224 deletions(-) diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 857e7686b..5ef77882e 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:20:50Z" + generated_at: "2026-05-03T15:25:57Z" model: gpt-5.5 provider: openai - source_hash: 2300e613cd54084c533a0328bc7e1d08f677360e213cb7f3d9364e1e82a30020 + source_hash: c3b97d3dff3d3a91db568dc689f82c0b63ad8028fb716cc772e84d7afe071869 source_path: channels/telegram.md workflow: 16 --- -Готово до production для особистих повідомлень ботів і груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий. +Готово до продакшену для особистих повідомлень ботам і груп через grammY. Long polling є режимом за замовчуванням; режим webhook є необов'язковим. - - Політика особистих повідомлень за замовчуванням для Telegram — зв’язування. + + Політика особистих повідомлень за замовчуванням для Telegram — сполучення. - - Міжканальна діагностика та інструкції з відновлення. + + Міжканальна діагностика та плейбуки відновлення. Повні шаблони й приклади конфігурації каналів. @@ -30,7 +30,7 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я користувача точно `@BotFather`). + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. @@ -51,12 +51,12 @@ x-i18n: } ``` - Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації або середовищі, потім запустіть Gateway. + Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. - + ```bash openclaw gateway @@ -64,7 +64,7 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди зв’язування спливають через 1 годину. + Коди сполучення діють 1 годину. @@ -74,21 +74,21 @@ openclaw pairing approve telegram -Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним варіантом із середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. -## Налаштування на стороні Telegram +## Налаштування на боці Telegram - Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує те, які групові повідомлення вони отримують. + Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі групові повідомлення, зробіть одне з цього: + Якщо бот має бачити всі групові повідомлення, виконайте одне з двох: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. + Під час перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну. @@ -101,13 +101,13 @@ openclaw pairing approve telegram - - `/setjoingroups`, щоб дозволити або заборонити додавання до груп + - `/setjoingroups`, щоб дозволити/заборонити додавання до груп - `/setprivacy` для поведінки видимості в групах -## Контроль доступу й активація +## Контроль доступу та активація @@ -118,21 +118,21 @@ openclaw pairing approve telegram - `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: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний дозволений список облікового запису після злиття все ще не містить явного wildcard. - `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі особисті повідомлення й відхиляється валідацією конфігурації. + У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` вважається межею безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний список allowlist облікового запису після злиття все ще не містить явного wildcard. + `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі особисті повідомлення й відхиляється перевіркою конфігурації. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися й ваша конфігурація містить записи дозволеного списку `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токена бота Telegram). - Якщо раніше ви покладалися на файли дозволених списків зі сховища зв’язувань, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках із дозволеним списком (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + Якщо ви оновилися й ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб розв'язати їх (best-effort; потрібен токен бота Telegram). + Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була довговічною в конфігурації (замість залежності від попередніх схвалень зв’язування). + Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була стійкою в конфігурації (замість залежності від попередніх підтверджень сполучення). - Поширена плутанина: схвалення зв’язування для особистих повідомлень не означає «цей відправник авторизований всюди». - Зв’язування надає доступ до особистих повідомлень. Якщо власника команд ще не існує, перше схвалене зв’язування також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. - Авторизація відправника в групі все одно походить із явних дозволених списків у конфігурації. - Якщо ви хочете «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. + Поширена плутанина: підтвердження сполучення для особистих повідомлень не означає "цей відправник авторизований всюди". + Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше підтверджене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й підтвердження exec мали явний обліковий запис оператора. + Авторизація відправника в групах усе ще походить із явних allowlist у конфігурації. + Якщо ви хочете "мене авторизовано один раз, і працюють як особисті повідомлення, так і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram @@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot/getUpdates" - + Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - - немає конфігурації `groups`: - - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи + - немає config `groups`: + - з `groupPolicy: "open"`: будь-яка група може пройти перевірки group-ID - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - - `groups` налаштовано: діє як дозволений список (явні ID або `"*"`) + - `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`. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від'ємні ID чатів належать у `channels.telegram.groups`. Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): автентифікація відправника в групі **не** успадковує схвалення зі сховища зв’язувань для особистих повідомлень. - Зв’язування залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи чи теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища зв’язувань. + Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує підтвердження зі сховища сполучень для особистих повідомлень. + Сполучення лишається тільки для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням закривається при помилці з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` явно не задано. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює fail-closed із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -211,9 +211,9 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є дозволеним списком груп Telegram. + Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. - - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте від'ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. @@ -222,9 +222,9 @@ curl "https://api.telegram.org/bot/getUpdates" - Групові відповіді за замовчуванням потребують згадки. + Відповіді в групі за замовчуванням потребують згадки. - Згадка може надходити з: + Згадка може походити з: - нативної згадки `@botusername`, або - шаблонів згадок у: @@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для сталості використовуйте конфігурацію. + Вони оновлюють лише стан сесії. Використовуйте config для збереження. Приклад сталої конфігурації: @@ -256,22 +256,22 @@ curl "https://api.telegram.org/bot/getUpdates" - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` - або прочитайте `chat.id` з `openclaw logs --follow` - - або перевірте Bot API `getUpdates` + - або перегляньте Bot API `getUpdates` ## Поведінка runtime -- Telegram належить процесу Gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали). +- Telegram належить процесу gateway. +- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь назад у Telegram (модель не вибирає канали). - Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та placeholders для медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими. -- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням тримає особисті повідомлення в плоскій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій тем в особистих повідомленнях. -- Довге опитування використовує grammY runner із послідовністю на рівні чату й потоку. Загальна паралельність приймача runner використовує `agents.defaults.maxConcurrent`. -- Довге опитування захищене всередині кожного процесу Gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший Gateway OpenClaw, скрипт або зовнішній poller використовує той самий токен. -- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують через 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час довготривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). +- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми лишалися ізольованими. +- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID thread для відповідей, але за замовчуванням тримає особисті повідомлення в пласкій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію topic, коли ви навмисно хочете ізоляцію сесій тем в особистих повідомленнях. +- Long polling використовує grammY runner із послідовністю per-chat/per-thread. Загальна конкуренція runner sink використовує `agents.defaults.maxConcurrent`. +- Long polling захищений усередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller. +- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час довготривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються override для окремих облікових записів. +- Telegram Bot API не має підтримки read-receipt (`sendReadReceipts` не застосовується). ## Довідник функцій @@ -284,12 +284,12 @@ curl "https://api.telegram.org/bot/getUpdates" Вимога: - - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна трансляція попереднього перегляду) + - `channels.telegram.streaming` є `off | partial | block | progress` (за замовчуванням: `partial`) + - `progress` мапиться на `partial` у Telegram (сумісність із міжканальним іменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна streaming попереднього перегляду) - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх у `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніших версій. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і новіших версій. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,16 +306,16 @@ 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`, коли потрібно залишити лише редагування попереднього перегляду відповіді, приховавши рядки стану прогресу інструментів. - Для відповідей лише текстом: + Для відповідей лише з текстом: - - короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці - - попередні перегляди, старші приблизно однієї хвилини: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці + - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіавмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіанавантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потокове передавання попереднього перегляду окреме від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Потік міркувань лише для Telegram: @@ -324,25 +324,25 @@ curl "https://api.telegram.org/bot/getUpdates" - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Текст у стилі Markdown перетворюється на безпечний для Telegram HTML. + - Markdown-подібний текст рендериться у безпечний для Telegram HTML. - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. - Попередні перегляди посилань увімкнено за замовчуванням, їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`. + Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені за допомогою `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`. + + Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Стандартні значення нативних команд: + Типові значення для вбудованих команд: - - `commands.native: "auto"` вмикає нативні команди для Telegram + - `commands.native: "auto"` вмикає вбудовані команди для Telegram - Додайте власні записи в меню команд: + Додайте власні записи меню команд: ```json5 { @@ -359,47 +359,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (початковий `/` видаляється, літери переводяться в нижній регістр) - - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - власні команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються й записуються в журнал + - назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) + - дійсний шаблон: `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` було задано як повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як збій очищення Webhook. + - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблокований. - ### Команди сполучення пристрою (Plugin `device-pair`) + ### Команди сполучення пристроїв (Plugin `device-pair`) Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування - 2. вставте код у застосунок iOS - 3. `/pair pending` перелічує запити, що очікують (зокрема роль/області) + 2. вставте код в iOS app + 3. `/pair pending` показує очікувані запити (зокрема роль/області) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один запит, що очікує + - `/pair approve`, коли є лише один очікуваний запит - `/pair approve latest` для найновішого - Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролям, які не є операторськими, усе одно потрібні області під власним префіксом ролі. + Код налаштування містить короткоживучий 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 { @@ -464,7 +464,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Дії інструментів Telegram включають: - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) @@ -473,26 +473,26 @@ 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` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ситуативне повторне розв’язання SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` зараз увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги гілкування відповідей у згенерованому виводі: + + Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск + - `[[reply_to_current]]` відповідає на повідомлення, що запустило дію - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -501,29 +501,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли гілкування відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли потоки відповідей увімкнені й доступний оригінальний текст або підпис Telegram, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує текст нативної цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявне гілкування відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - - Супергрупи форуму: + + Форумні супергрупи: - ключі сесій тем додають `:topic:` - - відповіді та індикатор введення спрямовуються в гілку теми + - відповіді та typing спрямовуються в потік теми - шлях конфігурації теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії введення все одно включають `message_thread_id` + - дії typing усе одно включають `message_thread_id` - Успадкування теми: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` належить лише темі й не успадковується зі стандартних значень групи. + Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` застосовується лише до теми й не успадковується з типових значень групи. - **Маршрутизація агентів за темами**: кожна тема може маршрутизуватися до іншого агента шляхом встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента, якщо встановити `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -543,26 +543,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із темою, наприклад `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, як-от `-1001234567890:topic:42`). Наразі обмежено форумними темами в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Thread-bound ACP spawn з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження spawn у темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). + **Запуск ACP, прив’язаний до потоку, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді на плоских сесіях; вони використовують ключі сесій із підтримкою гілок лише тоді, коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня для стандартного значення облікового запису або `direct..threadReplies` для одного DM. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають DM-маршрутизацію й метадані відповіді у пласких сесіях; вони використовують thread-aware ключі сесій лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня для типового значення облікового запису або `direct..threadReplies` для одного DM. - + ### Аудіоповідомлення - Telegram розрізняє голосові нотатки та аудіофайли. + Telegram розрізняє голосові нотатки й аудіофайли. - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, - ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий - транскрипт, тому голосові повідомлення, що залежать від згадок, продовжують працювати. + - вхідні транскрипти голосових нотаток оформлюються як машинно згенерований, + недовірений текст у контексті агента; виявлення згадки все одно використовує сирий + транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. Приклад дії повідомлення: @@ -578,7 +578,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли та відеонотатки. + Telegram розрізняє відеофайли й відеонотатки. Приклад дії повідомлення: @@ -598,7 +598,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (заповнювач ``) + - статичний WEBP: завантажується та обробляється (placeholder ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -614,7 +614,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision. Увімкніть дії зі стікерами: @@ -630,7 +630,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Надіслати дію наліпки: + Надіслати дію стікера: ```json5 { @@ -641,7 +641,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Шукати кешовані наліпки: + Шукати кешовані стікери: ```json5 { @@ -657,53 +657,53 @@ curl "https://api.telegram.org/bot/getUpdates" Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). - Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт: + Коли це ввімкнено, OpenClaw додає в чергу системні події на кшталт: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` Конфігурація: - - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) Примітки: - - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращої спроби через кеш надісланих повідомлень). - - Події реакцій усе одно дотримуються засобів контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизованих відправників відкидають. - - Telegram не надає ID тем в оновленнях реакцій. - - групи без форуму спрямовуються до сеансу групового чату - - групи з форумом спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). + - Події реакцій усе ще поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ідентифікатори гілок в оновленнях реакцій. + - групи без форумів спрямовуються до сеансу групового чату + - групи з форумами спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми `allowed_updates` для опитування/webhook автоматично включає `message_reaction`. - + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок вирішення: + Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - запасний емодзі ідентичності агента (`agents.list[].identity.emoji`, else "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode-емодзі (наприклад, "👀"). - - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Telegram очікує емодзі Unicode (наприклад "👀"). + - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнено типово (`configWrites !== false`). + Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`). Записи, ініційовані Telegram, включають: - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потрібно ввімкнути команди) + - `/config set` і `/config unset` (потребує ввімкнення команд) - Вимкнення: + Вимкнути: ```json5 { @@ -717,38 +717,38 @@ curl "https://api.telegram.org/bot/getUpdates" - - Типовим є довге опитування. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типово `/telegram-webhook`, `127.0.0.1`, `8787`). + + За замовчуванням використовується тривале опитування. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. - Режим webhook перевіряє запобіжники запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі лінії бота для кожного чату/кожної теми, що використовуються довгим опитуванням, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим webhook перевіряє захисні умови запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі лінії бота для кожного чату/теми, що використовуються тривалим опитуванням, тож повільні ходи агента не затримують ACK доставки Telegram. - - - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. - - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти бота обмежують налаштовані значення нижче 60-секундного запобіжника запитів вихідного тексту/набирання, щоб grammY не перервав доставку видимої відповіді до того, як спрацюють транспортний запобіжник і запасний шлях OpenClaw. Довге опитування й надалі використовує 45-секундний запобіжник запиту `getUpdates`, щоб неактивні опитування не залишалися покинутими безкінечно. - - `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання опитування. - - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається в отриманому вигляді. - - списки дозволів Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + + - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. + - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. + - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується стандарт grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисного ліміту вихідних текстових/typing-запитів, щоб grammY не переривав доставку видимої відповіді до того, як зможуть спрацювати транспортний захист і резервний механізм OpenClaw. Тривале опитування все ще використовує 45-секундний захисний ліміт запиту `getUpdates`, щоб бездіяльні опитування не залишалися покинутими безкінечно. + - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування. + - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. + - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. + - Списки дозволів Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - Елементи керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка остаточної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до з’єднання, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до помічників надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до встановлення з’єднання, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення. - Ціль надсилання CLI може бути числовим ID чату або іменем користувача: + Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача: ```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 \ @@ -763,13 +763,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) + - `--thread-id` для тем форуму (або використайте ціль `:topic:`) - Надсилання через Telegram також підтримує: + Надсилання 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 як документи замість стиснених фото або завантажень анімованих медіа Обмеження дій: @@ -778,37 +778,37 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - - Telegram підтримує підтвердження exec у DM затверджувачів і може необов’язково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ідентифікаторами користувачів Telegram. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача) - - `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача) + - `channels.telegram.execApprovals.approvers` (повертається до числових ідентифікаторів власників із `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось затверджувачем exec. Перше затверджене спарювання в DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще не існує, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене спарювання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ідентифікаторів у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `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`). Ідентифікатори схвалення з префіксом `plugin:` розв’язуються через схвалення Plugin; інші спершу розв’язуються через схвалення exec. - Див. [Підтвердження exec](/uk/tools/exec-approvals). + Див. [Схвалення exec](/uk/tools/exec-approvals). -## Керування відповідями на помилки +## Елементи керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цією поведінкою керують два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, 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,52 +833,52 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть і повторно додайте бота до групи + - потім видаліть і знову додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - - швидкий тест сесії: `/activation always`. + - `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство. + - швидкий тест сеансу: `/activation always`. - - коли існує `channels.telegram.groups`, групу потрібно вказати в списку (або додати `"*"`) + - коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте ідентичність відправника (спарювання та/або числовий `allowFrom`) - - авторизація команд усе одно застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість команд plugin/Skills/користувацьких команд або вимкніть нативні меню - - виклики запуску `deleteMyCommands` / `setMyCommands` і виклики введення `sendChatAction` обмежені та повторюються один раз через резервний транспорт Telegram у разі тайм-ауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` + - авторизуйте свою ідентичність відправника (спарювання та/або числовий `allowFrom`) + - авторизація команд усе ще застосовується, навіть коли політика групи має значення `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть нативні меню + - Виклики запуску `deleteMyCommands` / `setMyCommands` і typing-виклики `sendChatAction` обмежені та повторюються один раз через транспортний резерв Telegram у разі тайм-ауту запиту. Постійні мережеві/fetch-помилки зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` - - `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота. - - Скопіюйте повторно або згенеруйте заново токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням. - - `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій неправильного токена до пізніших викликів API. - - Якщо `deleteWebhook` завершується збоєм через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до long polling замість виконання ще одного керівного виклику перед опитуванням. Активний webhook проявляється як конфлікт `getUpdates`; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення webhook. - - Після успішної перевірки `getMe` під час запуску OpenClaw повторно використовує цю ідентичність бота для запуску опитування grammY, тож runner не потребує другого `getMe` перед першим `getUpdates`. + - `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. + - Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. + - Деякі хости спершу розв'язують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API. - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки. - - Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не замале значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення, нижчі за запобіжники вихідних запитів і запитів `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці запобіжники. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності довгого опитування за замовчуванням. - - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис опитування не завершив `getUpdates` після стартового пільгового періоду, коли запущений Webhook-обліковий запис не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність транспорту опитування застаріла. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через зупинку опитування. Постійні зупинки зазвичай указують на проблеми proxy, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`. - - Telegram також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й стандартних змінних середовища proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API. - - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: + - Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, щоб виконавцю не був потрібен другий `getMe` перед першим `getUpdates`. + - Якщо `deleteWebhook` завершується збоєм через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до long polling замість виконання ще одного передопитувального виклику площини керування. Webhook, який усе ще активний, проявляється як конфлікт `getUpdates`; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення Webhook. + - Якщо сокети Telegram перевикористовуються з коротким фіксованим інтервалом, перевірте, чи не має `channels.telegram.timeoutSeconds` низьке значення; клієнти ботів обмежують налаштовані значення нижче за захисні межі вихідних запитів і запитів `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці межі. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеної перевірки працездатності long-poll за замовчуванням. + - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис опитування не завершив `getUpdates` після пільгового періоду запуску, коли запущений обліковий запис Webhook не завершив `setWebhook` після пільгового періоду запуску, або коли остання успішна активність транспорту опитування застаріла. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через зупинку опитування. Постійні зупинки зазвичай указують на проблеми з proxy, DNS, IPv6 або вихідним TLS між хостом і `api.telegram.org`. + - Telegram також враховує proxy-змінні середовища процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища, а стандартні proxy-змінні середовища відсутні, Telegram також використовує цей URL для транспорту Bot API. + - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -886,8 +886,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: @@ -896,11 +896,11 @@ channels: autoSelectFamily: false ``` - - Відповіді з діапазону тестування RFC 2544 (`198.18.0.0/15`) уже дозволені - для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або + - Відповіді діапазону RFC 2544 для бенчмарків (`198.18.0.0/15`) уже дозволені + для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або прозорий proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального використання адресу під час завантаження медіа, ви можете явно ввімкнути - обхід лише для Telegram: + приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете + увімкнути обхід лише для Telegram: ```yaml channels: @@ -909,25 +909,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Та сама можливість явного ввімкнення доступна для кожного облікового запису за адресою + - Такий самий явний дозвіл доступний для кожного облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште - небезпечний прапорець вимкненим. Медіа Telegram уже дозволяють діапазон - тестування RFC 2544 за замовчуванням. + - Якщо ваш proxy розв'язує медіахости Telegram у `198.18.x.x`, спершу залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон + бенчмарків RFC 2544 за замовчуванням. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram - від SSRF. Використовуйте це лише для довірених proxy-середовищ під контролем оператора, + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти Telegram + media SSRF. Використовуйте це лише для довірених proxy-середовищ, керованих оператором, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони - синтезують приватні або спеціального використання відповіді поза діапазоном тестування - RFC 2544. Залишайте це вимкненим для звичайного публічного доступу до Telegram через інтернет. + синтезують приватні відповіді або відповіді спеціального призначення поза діапазоном + бенчмарків RFC 2544. Залишайте це вимкненим для звичайного публічного інтернет-доступу до Telegram. - Перевизначення середовища (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірте DNS-відповіді: ```bash dig +short api.telegram.org A @@ -937,23 +937,23 @@ 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"`) -- схвалення виконання: `execApprovals`, `accounts.*.execApprovals` +- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) +- контроль доступу: `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.preview.toolProgress`, `blockStreaming` +- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` @@ -963,7 +963,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.*`. +Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане @@ -973,18 +973,18 @@ dig +short api.telegram.org AAAA Сполучіть користувача Telegram із Gateway. - Поведінка allowlist для груп і тем. + Поведінка списку дозволених груп і тем. - Маршрутизуйте вхідні повідомлення агентам. + Маршрутизуйте вхідні повідомлення до агентів. Модель загроз і посилення захисту. - + Зіставляйте групи й теми з агентами. - + Діагностика між каналами.