diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md
index cf5f97462..1af62c0aa 100644
--- a/docs/uk/channels/telegram.md
+++ b/docs/uk/channels/telegram.md
@@ -1,30 +1,30 @@
---
read_when:
- - Робота над функціями Telegram або Webhook
-summary: Статус підтримки бота Telegram, можливості та конфігурація
+ - Працює над функціями Telegram або Webhook'ами
+summary: Статус підтримки бота Telegram, можливості та налаштування
title: Telegram
x-i18n:
- generated_at: "2026-04-21T00:04:35Z"
+ generated_at: "2026-04-21T00:17:10Z"
model: gpt-5.4
provider: openai
- source_hash: 90a26051a3b7579e0d465c54bd3fac562d3442f6030b21e903cd4ec7fcf12e74
+ source_hash: b5c70775b55d4923a31ad8bae7f4c6e7cbae754c05c3a578180d63db2b59e39a
source_path: channels/telegram.md
workflow: 15
---
# Telegram (Bot API)
-Статус: готовий до продакшну для DM бота + груп через grammY. Довге опитування — типовий режим; режим Webhook — необов’язковий.
+Статус: готовий до продакшену для DM бота + груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook є необов’язковим.
-
- Типова політика DM для Telegram — з’єднання.
+
+ Типова політика DM для Telegram — сполучення.
- Міжканальна діагностика та інструкції з відновлення.
+ Міжканальна діагностика та сценарії відновлення.
-
- Повні шаблони та приклади конфігурації каналу.
+
+ Повні шаблони та приклади конфігурації каналів.
@@ -32,9 +32,9 @@ x-i18n:
- Відкрийте Telegram і почніть чат з **@BotFather** (переконайтеся, що ім’я користувача точно `@BotFather`).
+ Відкрийте Telegram і почніть чат з **@BotFather** (переконайтеся, що хендл точно `@BotFather`).
- Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
+ Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
@@ -53,12 +53,12 @@ x-i18n:
}
```
- Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише для типового облікового запису).
- Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть Gateway.
+ Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням).
+ Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
-
+
```bash
openclaw gateway
@@ -66,7 +66,7 @@ openclaw pairing list telegram
openclaw pairing approve telegram
```
- Коди з’єднання спливають через 1 годину.
+ Коди сполучення дійсні протягом 1 години.
@@ -76,35 +76,35 @@ openclaw pairing approve telegram
-Порядок визначення токена залежить від облікового запису. На практиці значення з config мають пріоритет над резервним значенням з env, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису.
+Порядок визначення токена залежить від облікового запису. На практиці значення з config мають пріоритет над резервним значенням із env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
## Налаштування на боці Telegram
-
- Для ботів Telegram типово ввімкнено **Privacy Mode**, який обмежує, які повідомлення в групі вони отримують.
+
+ Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, який обмежує, які повідомлення групи вони отримують.
- Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого:
+ Якщо бот має бачити всі повідомлення групи, виконайте одну з дій:
- - вимкніть режим конфіденційності через `/setprivacy`, або
+ - вимкніть режим приватності через `/setprivacy`, або
- зробіть бота адміністратором групи.
- Після перемикання режиму конфіденційності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну.
+ Після перемикання режиму приватності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміни.
Статус адміністратора керується в налаштуваннях групи Telegram.
- Боти-адміністратори отримують усі повідомлення групи, що корисно для завжди активної поведінки в групі.
+ Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групах.
- `/setjoingroups` — дозволити/заборонити додавання до груп
- - `/setprivacy` — поведінка видимості в групі
+ - `/setprivacy` — керування видимістю в групах
@@ -115,22 +115,22 @@ openclaw pairing approve telegram
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
- - `pairing` (типово)
- - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
- - `open` (потрібно, щоб `allowFrom` містив `"*"`)
+ - `pairing` (за замовчуванням)
+ - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`)
+ - `open` (потребує, щоб `allowFrom` містив `"*"`)
- `disabled`
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config.
Під час налаштування запитуються лише числові ID користувачів.
- Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (best-effort; потрібен токен бота Telegram).
- Якщо ви раніше покладалися на файли allowlist зі сховища з’єднань, `openclaw doctor --fix` може відновити записи до `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
+ Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб перетворити їх (у межах можливого; потрібен токен бота 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 не означає, що «цей відправник авторизований скрізь».
+ Сполучення надає доступ лише до DM. Авторизація відправників у групах і надалі визначається явними allowlist у config.
+ Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`.
### Як знайти свій ID користувача Telegram
@@ -146,7 +146,7 @@ openclaw pairing approve telegram
curl "https://api.telegram.org/bot/getUpdates"
```
- Сторонній спосіб (менше приватності): `@userinfobot` або `@getidsbot`.
+ Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`.
@@ -156,23 +156,23 @@ curl "https://api.telegram.org/bot/getUpdates"
1. **Які групи дозволені** (`channels.telegram.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` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує `allowFrom` як резервне значення.
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються).
- Не вказуйте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`.
- Нечислові записи ігноруються для авторизації відправника.
- Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища з’єднань для DM.
- З’єднання залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
- Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища з’єднань.
- Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте цільові групи в `channels.telegram.groups`.
- Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime типово працює в fail-closed режимі з `groupPolicy="allowlist"`, якщо лише `channels.defaults.groupPolicy` не задано явно.
+ Не додавайте 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`.
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
@@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates"
}
```
- Приклад: дозволити лише певним користувачам в одній конкретній групі:
+ Приклад: дозволити лише конкретним користувачам в одній конкретній групі:
```json5
{
@@ -211,15 +211,15 @@ curl "https://api.telegram.org/bot/getUpdates"
Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram.
- - Вказуйте від’ємні ID груп або супергруп Telegram, наприклад `-1001234567890`, у `channels.telegram.groups`.
- - Вказуйте ID користувачів Telegram, наприклад `8734062810`, у `groupAllowFrom`, якщо хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота.
- - Використовуйте `groupAllowFrom: ["*"]` лише якщо хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
+ - Додавайте від’ємні ID груп або супергруп Telegram, такі як `-1001234567890`, до `channels.telegram.groups`.
+ - Додавайте ID користувачів Telegram, такі як `8734062810`, до `groupAllowFrom`, якщо хочете обмежити, хто саме всередині дозволеної групи може викликати бота.
+ - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
-
- Відповіді в групі типово вимагають згадки.
+
+ Відповіді в групах за замовчуванням потребують згадки.
Згадка може надходити з:
@@ -228,12 +228,12 @@ curl "https://api.telegram.org/bot/getUpdates"
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
- Перемикачі команд на рівні сесії:
+ Перемикачі команд рівня сесії:
- `/activation always`
- `/activation mention`
- Вони оновлюють лише стан сесії. Для постійності використовуйте config.
+ Вони оновлюють лише стан сесії. Для постійного збереження використовуйте config.
Приклад постійної конфігурації:
@@ -251,28 +251,28 @@ curl "https://api.telegram.org/bot/getUpdates"
Як отримати ID групового чату:
- - перешліть повідомлення з групи до `@userinfobot` / `@getidsbot`
- - або прочитайте `chat.id` з `openclaw logs --follow`
- - або перегляньте Bot API `getUpdates`
+ - переслати повідомлення з групи до `@userinfobot` / `@getidsbot`
+ - або прочитати `chat.id` з `openclaw logs --follow`
+ - або перевірити Bot API `getUpdates`
## Поведінка runtime
-- Telegram належить процесу Gateway.
+- Telegram належить процесу gateway.
- Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали).
-- Вхідні повідомлення нормалізуються у спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
-- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими.
-- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії з урахуванням потоку та зберігає ID потоку для відповідей.
-- Довге опитування використовує grammY runner із послідовністю на рівні чату/потоку. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
-- Перезапуски watchdog для довгого опитування спрацьовують типово після 120 секунд без завершеної активності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
-- Telegram Bot API не підтримує read receipt (`sendReadReceipts` не застосовується).
+- Вхідні повідомлення нормалізуються до спільної оболонки каналу з метаданими відповіді та заповнювачами медіа.
+- Сесії груп ізольовані за ID групи. Теми форуму додають `:topic:`, щоб зберегти ізоляцію тем.
+- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесій і зберігає ID потоку для відповідей.
+- Довге опитування використовує grammY runner з послідовністю для кожного чату/потоку. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
+- Перезапуски сторожового механізму довгого опитування спрацьовують за замовчуванням після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще виникають хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
+- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
## Довідник можливостей
-
+
OpenClaw може транслювати часткові відповіді в реальному часі:
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
@@ -280,54 +280,54 @@ curl "https://api.telegram.org/bot/getUpdates"
Вимога:
- - `channels.telegram.streaming` має значення `off | partial | block | progress` (типово: `partial`)
- - `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням)
+ - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
+ - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним найменуванням)
- застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` автоматично зіставляються
Для відповідей лише з текстом:
- - DM: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
- - група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
+ - DM: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)
+ - група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)
- Для складних відповідей (наприклад, із медіанавантаженням) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
+ Для складних відповідей (наприклад, з медіа), OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
- Потокове передавання попереднього перегляду відокремлене від block streaming. Коли block streaming для Telegram увімкнено явно, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
+ Потоковий попередній перегляд відокремлений від block streaming. Якщо для Telegram явно ввімкнено block streaming, OpenClaw пропускає потоковий попередній перегляд, щоб уникнути подвійного потокового виведення.
- Якщо нативний транспорт чернеток недоступний/відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
+ Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
Потік reasoning лише для Telegram:
- - `/reasoning stream` надсилає reasoning у живий попередній перегляд під час генерації
+ - `/reasoning stream` надсилає reasoning у live preview під час генерації
- фінальна відповідь надсилається без тексту reasoning
-
+
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
- - Сирий HTML моделі екранується, щоб зменшити збої розбору в Telegram.
+ - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram.
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
- Попередній перегляд посилань увімкнено типово, його можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
+ Попередній перегляд посилань увімкнений за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`.
- Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`.
+ Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
- Типові налаштування нативних команд:
+ Типові значення для нативних команд:
- `commands.native: "auto"` вмикає нативні команди для Telegram
- Додайте користувацькі записи меню команд:
+ Додавання користувацьких записів до меню команд:
```json5
{
channels: {
telegram: {
customCommands: [
- { command: "backup", description: "Git-резервна копія" },
+ { command: "backup", description: "Резервна копія Git" },
{ command: "generate", description: "Створити зображення" },
],
},
@@ -337,40 +337,40 @@ curl "https://api.telegram.org/bot/getUpdates"
Правила:
- - імена нормалізуються (видалення початкового `/`, нижній регістр)
- - дійсний шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
+ - імена нормалізуються (прибирається початковий `/`, нижній регістр)
+ - припустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
- користувацькі команди не можуть перевизначати нативні команди
- - конфлікти/дублікати пропускаються й логуються
+ - конфлікти/дублікати пропускаються та записуються в журнал
Примітки:
- користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично
- - команди Plugin/Skills все одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram
+ - команди Plugin/Skills усе одно можуть працювати при ручному введенні, навіть якщо вони не показані в меню Telegram
- Якщо нативні команди вимкнено, вбудовані буде видалено. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
+ Якщо нативні команди вимкнені, вбудовані команди видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
Поширені збої під час налаштування:
- - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
- - `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані.
+ - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
+ - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-запити до `api.telegram.org` заблоковані.
- ### Команди з’єднання пристрою (`device-pair` Plugin)
+ ### Команди сполучення пристроїв (Plugin `device-pair`)
Коли встановлено Plugin `device-pair`:
1. `/pair` генерує код налаштування
- 2. вставте код у застосунок iOS
- 3. `/pair pending` показує список запитів, що очікують на розгляд (зокрема роль/scopes)
- 4. схваліть запит:
- - `/pair approve ` для явного схвалення
- - `/pair approve`, коли є лише один запит, що очікує на розгляд
+ 2. вставте код у застосунку iOS
+ 3. `/pair pending` показує список запитів, що очікують розгляду (включно з роллю/scopes)
+ 4. підтвердьте запит:
+ - `/pair approve ` для явного підтвердження
+ - `/pair approve`, коли є лише один запит, що очікує розгляду
- `/pair approve latest` для найновішого
- Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен primary Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролям, які не є оператором, як і раніше потрібні scopes під префіксом їхньої власної ролі.
+ Код налаштування містить короткостроковий bootstrap-токен. Вбудована передача bootstrap-запиту зберігає токен первинного Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-scopes мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, як і раніше потребують scopes під власним префіксом ролі.
- Якщо пристрій повторює спробу зі зміненими даними auth (наприклад, role/scopes/public key), попередній запит, що очікує на розгляд, заміщується, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
+ Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній запит, що очікував розгляду, замінюється, а новий запит використовує інший `requestId`. Перед підтвердженням повторно виконайте `/pair pending`.
- Докладніше: [З’єднання](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
+ Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
@@ -413,7 +413,7 @@ curl "https://api.telegram.org/bot/getUpdates"
- `dm`
- `group`
- `all`
- - `allowlist` (типово)
+ - `allowlist` (за замовчуванням)
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
@@ -440,26 +440,26 @@ curl "https://api.telegram.org/bot/getUpdates"
-
+
Дії інструментів Telegram включають:
- - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
+ - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
+ - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
- Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
+ Дії повідомлень каналу надають зручні псевдоніми (`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 (startup/reload), тож шляхи дій не виконують ad-hoc повторного визначення SecretRef для кожного надсилання.
+ Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
+ Надсилання в runtime використовує активний знімок config/secrets (startup/reload), тому шляхи дій не виконують спеціального повторного визначення `SecretRef` під час кожного надсилання.
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
@@ -468,16 +468,16 @@ curl "https://api.telegram.org/bot/getUpdates"
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
- - `[[reply_to_current]]` відповідає на повідомлення-тригер
- - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram
+ - `[[reply_to_current]]` — відповісти на повідомлення-тригер
+ - `[[reply_to:]]` — відповісти на конкретний ID повідомлення Telegram
`channels.telegram.replyToMode` керує обробкою:
- - `off` (типово)
+ - `off` (за замовчуванням)
- `first`
- `all`
- Примітка: `off` вимикає неявний потік відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
+ Примітка: `off` вимикає неявне групування відповідей у потоки. Явні теги `[[reply_to_*]]` однаково враховуються.
@@ -485,19 +485,19 @@ curl "https://api.telegram.org/bot/getUpdates"
Супергрупи форуму:
- ключі сесій тем додають `:topic:`
- - відповіді та індикатор набору тексту спрямовуються до потоку теми
- - шлях config теми:
+ - відповіді та індикатор набору націлюються на потік теми
+ - шлях config для теми:
`channels.telegram.groups..topics.`
- Особливий випадок загальної теми (`threadId=1`):
+ Спеціальний випадок загальної теми (`threadId=1`):
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
- - дії індикатора набору тексту все одно містять `message_thread_id`
+ - дії індикатора набору все одно включають `message_thread_id`
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
- `agentId` діє лише для теми й не успадковується з типових налаштувань групи.
+ `agentId` стосується лише теми й не успадковується від значень групи за замовчуванням.
- **Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через `agentId` у config теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад:
+ **Маршрутизація агента для кожної теми**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це надає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад:
```json5
{
@@ -506,9 +506,9 @@ curl "https://api.telegram.org/bot/getUpdates"
groups: {
"-1001234567890": {
topics: {
- "1": { agentId: "main" }, // Загальна тема → main агент
- "3": { agentId: "zu" }, // Тема розробки → zu агент
- "5": { agentId: "coder" } // Рев’ю коду → coder агент
+ "1": { agentId: "main" }, // Загальна тема → агент main
+ "3": { agentId: "zu" }, // Тема розробки → агент zu
+ "5": { agentId: "coder" } // Перевірка коду → агент coder
}
}
}
@@ -519,7 +519,7 @@ curl "https://api.telegram.org/bot/getUpdates"
Тоді кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
- **Постійне прив’язування тем ACP**: Теми форуму можуть закріплювати сесії ACP harness через typed ACP bindings верхнього рівня:
+ **Постійна прив’язка тем ACP**: Теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня:
- `bindings[]` з `type: "acp"` і `match.channel: "telegram"`
@@ -570,14 +570,14 @@ curl "https://api.telegram.org/bot/getUpdates"
}
```
- Наразі це обмежено темами форуму в групах і супергрупах.
+ Наразі це обмежено темами форумів у групах і супергрупах.
**Створення ACP, прив’язаного до потоку, з чату**:
- `/acp spawn --thread here|auto` може прив’язати поточну тему Telegram до нової сесії ACP.
- Подальші повідомлення в темі маршрутизуються безпосередньо до прив’язаної сесії ACP (без потреби в `/acp steer`).
- - Після успішного прив’язування OpenClaw закріплює повідомлення-підтвердження створення в межах теми.
- - Потрібен `channels.telegram.threadBindings.spawnAcpSessions=true`.
+ - Після успішної прив’язки OpenClaw закріплює повідомлення з підтвердженням створення прямо в темі.
+ - Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
Контекст шаблону включає:
@@ -586,7 +586,7 @@ curl "https://api.telegram.org/bot/getUpdates"
Поведінка потоків у DM:
- - приватні чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій і цілі відповідей з урахуванням потоку.
+ - приватні чати з `message_thread_id` зберігають маршрутизацію DM, але використовують thread-aware ключі сесій/цілі відповідей.
@@ -595,7 +595,7 @@ curl "https://api.telegram.org/bot/getUpdates"
Telegram розрізняє голосові повідомлення та аудіофайли.
- - типово: поведінка аудіофайлу
+ - за замовчуванням: поведінка аудіофайлу
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення
Приклад дії повідомлення:
@@ -612,7 +612,7 @@ curl "https://api.telegram.org/bot/getUpdates"
### Відеоповідомлення
- Telegram розрізняє відеофайли та video note.
+ Telegram розрізняє відеофайли та video notes.
Приклад дії повідомлення:
@@ -626,15 +626,15 @@ curl "https://api.telegram.org/bot/getUpdates"
}
```
- Video note не підтримують підписи; наданий текст повідомлення надсилається окремо.
+ Video notes не підтримують підписи; наданий текст повідомлення надсилається окремо.
### Стікери
Обробка вхідних стікерів:
- - статичний WEBP: завантажується та обробляється (заповнювач ``)
- - анімований TGS: пропускається
- - відео WEBM: пропускається
+ - статичні WEBP: завантажуються й обробляються (заповнювач ``)
+ - анімовані TGS: пропускаються
+ - відео WEBM: пропускаються
Поля контексту стікера:
@@ -681,7 +681,7 @@ curl "https://api.telegram.org/bot/getUpdates"
{
action: "sticker-search",
channel: "telegram",
- query: "кіт махає лапою",
+ query: "cat waving",
limit: 5,
}
```
@@ -689,30 +689,30 @@ curl "https://api.telegram.org/bot/getUpdates"
- Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень).
+ Реакції в Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень).
- Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
+ Якщо ввімкнено, OpenClaw ставить у чергу системні події на зразок:
- - `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 42`
+ - `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
Конфігурація:
- - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`)
- - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`)
+ - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`)
+ - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`)
Примітки:
- - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
+ - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (у межах можливого через кеш надісланих повідомлень).
- Події реакцій усе одно поважають механізми керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
- - Telegram не надає ID потоків в оновленнях реакцій.
- - групи без форумів маршрутизуються до сесії групового чату
- - групи-форуми маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
+ - Telegram не надає ID потоку в оновленнях реакцій.
+ - групи не-форумного типу маршрутизуються до сесії групового чату
+ - групи-форуми маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної вихідної теми
`allowed_updates` для polling/webhook автоматично включають `message_reaction`.
-
+
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
Порядок визначення:
@@ -720,21 +720,21 @@ curl "https://api.telegram.org/bot/getUpdates"
- `channels.telegram.accounts..ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- - резервний emoji з identity агента (`agents.list[].identity.emoji`, інакше "👀")
+ - резервне значення з емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
Примітки:
- - Telegram очікує emoji Unicode (наприклад, "👀").
+ - Telegram очікує Unicode-емодзі (наприклад, "👀").
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
- Запис config каналу типово ввімкнено (`configWrites !== false`).
+ Запис конфігурації каналу увімкнений за замовчуванням (`configWrites !== false`).
Записи, ініційовані Telegram, включають:
- - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
+ - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
- `/config set` і `/config unset` (потрібне ввімкнення команд)
Вимкнення:
@@ -751,38 +751,39 @@ curl "https://api.telegram.org/bot/getUpdates"
-
- Типово: довге опитування.
+
+ За замовчуванням: довге опитування.
Режим Webhook:
- задайте `channels.telegram.webhookUrl`
- - задайте `channels.telegram.webhookSecret` (обов’язково, якщо задано webhook URL)
- - необов’язково `channels.telegram.webhookPath` (типово `/telegram-webhook`)
- - необов’язково `channels.telegram.webhookHost` (типово `127.0.0.1`)
- - необов’язково `channels.telegram.webhookPort` (типово `8787`)
+ - задайте `channels.telegram.webhookSecret` (обов’язково, якщо задано URL Webhook)
+ - необов’язково `channels.telegram.webhookPath` (за замовчуванням `/telegram-webhook`)
+ - необов’язково `channels.telegram.webhookHost` (за замовчуванням `127.0.0.1`)
+ - необов’язково `channels.telegram.webhookPort` (за замовчуванням `8787`)
Типовий локальний listener для режиму Webhook прив’язується до `127.0.0.1:8787`.
- Якщо ваша публічна кінцева точка відрізняється, поставте перед нею reverse proxy і спрямуйте `webhookUrl` на публічний URL.
- Задайте `webhookHost` (наприклад, `0.0.0.0`), якщо вам навмисно потрібен зовнішній вхідний доступ.
+ Якщо ваша публічна кінцева точка відрізняється, поставте перед нею reverse proxy і вкажіть у `webhookUrl` публічний URL.
+ Встановіть `webhookHost` (наприклад, `0.0.0.0`), коли вам свідомо потрібен зовнішній вхідний трафік.
- - Типове значення `channels.telegram.textChunkLimit` — 4000.
- - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожні рядки) перед поділом за довжиною.
- - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіафайлів Telegram.
- - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типовий grammY).
- - Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
- - Додатковий контекст відповіді/цитати/пересилання наразі передається як отримано.
- - Allowlist 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.dmHistoryLimit`
- `channels.telegram.dms[""].historyLimit`
- Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.
- Ціллю надсилання CLI може бути числовий ID чату або ім’я користувача:
+ Ціль надсилання в CLI може бути числовим ID чату або ім’ям користувача:
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
@@ -808,71 +809,70 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
Надсилання Telegram також підтримує:
- - `--buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
- - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа
+ - `--buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
+ - `--force-document`, щоб надсилати вихідні зображення та GIF як документи, а не як стиснені фото чи анімовані медіазавантаження
Керування діями:
- - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування
+ - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
-
- Telegram підтримує погодження exec у DM затверджувачів і за бажанням може публікувати запити на погодження у вихідному чаті або темі.
+
+ Telegram підтримує підтвердження exec у DM осіб, що підтверджують, і за потреби може публікувати запити на підтвердження у вихідному чаті або темі.
Шлях config:
- `channels.telegram.execApprovals.enabled`
- - `channels.telegram.execApprovals.approvers` (необов’язково; якщо не задано, використовується резервне визначення числових ID власників із `allowFrom` і прямого `defaultTo`, коли це можливо)
- - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`)
+ - `channels.telegram.execApprovals.approvers` (необов’язково; як резервне значення використовуються числові ID власників, виведені з `allowFrom` і прямого `defaultTo`, коли це можливо)
+ - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`)
- `agentFilter`, `sessionFilter`
- Затверджувачі мають бути числовими ID користувачів Telegram. Telegram автоматично вмикає нативні погодження exec, коли `enabled` не задано або має значення `"auto"` і вдається визначити принаймні одного затверджувача — або з `execApprovals.approvers`, або з конфігурації числового власника облікового запису (`allowFrom` і direct-message `defaultTo`). Задайте `enabled: false`, щоб явно вимкнути Telegram як нативний клієнт погодження. В іншому разі запити на погодження повертаються до інших налаштованих маршрутів погодження або до резервної політики погодження exec.
+ Особи, що підтверджують, мають бути числовими ID користувачів Telegram. Telegram автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"`, і можна визначити принаймні одну особу, що підтверджує, або з `execApprovals.approvers`, або з конфігурації числового власника облікового запису (`allowFrom` і `defaultTo` для прямих повідомлень). Встановіть `enabled: false`, щоб явно вимкнути Telegram як нативний клієнт підтвердження. В інших випадках запити на підтвердження повертаються до інших налаштованих маршрутів підтвердження або до резервної політики підтвердження exec.
- Telegram також рендерить спільні кнопки погодження, які використовуються іншими чат-каналами. Нативний адаптер Telegram переважно додає маршрутизацію DM затверджувачів, fanout для каналів/тем і підказки набору тексту перед доставкою.
- Коли ці кнопки присутні, вони є основним UX погодження; OpenClaw
+ Telegram також рендерить спільні кнопки підтвердження, які використовуються іншими чат-каналами. Нативний адаптер Telegram переважно додає маршрутизацію DM для осіб, що підтверджують, fanout у канали/теми та підказки про набір перед доставкою.
+ Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw
має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує,
- що погодження в чаті недоступні або єдиний шлях — ручне погодження.
+ що підтвердження в чаті недоступні або ручне підтвердження — єдиний шлях.
Правила доставки:
- - `target: "dm"` надсилає запити на погодження лише до DM визначених затверджувачів
+ - `target: "dm"` надсилає запити на підтвердження лише в DM визначених осіб, що підтверджують
- `target: "channel"` надсилає запит назад у вихідний чат/тему Telegram
- - `target: "both"` надсилає і до DM затверджувачів, і до вихідного чату/теми
+ - `target: "both"` надсилає і в DM осіб, що підтверджують, і у вихідний чат/тему
- Лише визначені затверджувачі можуть погоджувати або відхиляти. Користувачі, які не є затверджувачами, не можуть використовувати `/approve` і не можуть використовувати кнопки погодження Telegram.
+ Лише визначені особи, що підтверджують, можуть підтверджувати або відхиляти. Особи, що не підтверджують, не можуть використовувати `/approve` і не можуть використовувати кнопки підтвердження Telegram.
- Поведінка визначення погодження:
+ Поведінка визначення підтвердження:
- - ID з префіксом `plugin:` завжди визначаються через погодження Plugin.
- - Інші ID спочатку намагаються пройти через `exec.approval.resolve`.
- - Якщо Telegram також авторизований для погоджень Plugin і Gateway повідомляє,
- що погодження exec невідоме або строк його дії сплив,
- Telegram один раз повторює спробу через
+ - ID з префіксом `plugin:` завжди визначаються через підтвердження Plugin.
+ - Інші ID спочатку пробують `exec.approval.resolve`.
+ - Якщо Telegram також авторизований для підтверджень Plugin і gateway повідомляє,
+ що підтвердження exec невідоме/прострочене, Telegram один раз повторює спробу через
`plugin.approval.resolve`.
- - Справжні відмови/помилки погодження exec не переходять мовчки до
- визначення погодження Plugin.
+ - Справжні відмови/помилки підтвердження exec не переходять мовчки до
+ визначення підтвердження Plugin.
- Доставка в канал показує текст команди в чаті, тому вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему і для запиту на погодження, і для подальших дій після погодження. Типово строк дії погоджень exec спливає через 30 хвилин.
+ Доставка в канал показує текст команди в чаті, тому вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему як для запиту на підтвердження, так і для подальших дій після підтвердження. Термін дії підтверджень exec за замовчуванням спливає через 30 хвилин.
- Вбудовані кнопки погодження також залежать від того, чи `channels.telegram.capabilities.inlineButtons` дозволяє цільову поверхню (`dm`, `group` або `all`).
+ Вбудовані кнопки підтвердження також залежать від того, чи дозволяє `channels.telegram.capabilities.inlineButtons` цільову поверхню (`dm`, `group` або `all`).
- Пов’язана документація: [Погодження exec](/uk/tools/exec-approvals)
+ Пов’язана документація: [Підтвердження exec](/uk/tools/exec-approvals)
-## Керування відповідями на помилки
+## Керування відповідями з помилками
-Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі config:
+Коли агент стикається з помилкою доставки або постачальника, Telegram може або відповісти текстом помилки, або приглушити його. Цю поведінку визначають два ключі config:
| Key | Values | Default | Description |
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає до чату дружнє повідомлення про помилку. `silent` повністю пригнічує відповіді з помилками. |
+| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приглушує відповіді з помилками. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в тому самому чаті. Запобігає спаму помилками під час збоїв. |
-Підтримуються перевизначення для окремого облікового запису, окремої групи та окремої теми (з тим самим успадкуванням, що й інші ключі config Telegram).
+Підтримуються перевизначення для окремих облікових записів, груп і тем (та саме успадкування, що й для інших ключів config Telegram).
```json5
{
@@ -895,39 +895,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
- - Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість.
+ - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
- BotFather: `/setprivacy` -> Disable
- - потім видаліть і знову додайте бота до групи
+ - потім видаліть бота й знову додайте його до групи
- `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки.
- - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити через membership probe.
- - швидка перевірка сесії: `/activation always`.
+ - `openclaw channels status --probe` може перевіряти явні числові ID груп; членство для шаблону `"*"` перевірити не можна.
+ - швидкий тест сесії: `/activation always`.
-
+
- - коли існує `channels.telegram.groups`, група має бути вказана в списку (або має бути `"*"`)
- - перевірте, що бот є учасником групи
- - перегляньте логи: `openclaw logs --follow` для причин пропуску
+ - коли існує `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`
+ - авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
+ - авторизація команд усе одно застосовується, навіть якщо політика групи — `open`
+ - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має надто багато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
+ - `setMyCommands failed` з помилками мережі/fetch зазвичай вказує на проблеми з доступністю DNS/HTTPS до `api.telegram.org`
- - Node 22+ + custom fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
- - На деяких хостах `api.telegram.org` спочатку визначається в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API.
- - Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
- - Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
- - На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
+ - Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
+ - На деяких хостах `api.telegram.org` спочатку резолвиться в IPv6; несправний вихід через IPv6 може викликати періодичні збої Telegram API.
+ - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює спробу для цих помилок як для відновлюваних мережевих помилок.
+ - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної життєздатності long-poll за замовчуванням.
+ - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` є справними, але ваш хост усе одно повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або TLS-виходом між хостом і `api.telegram.org`.
+ - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
```yaml
channels:
@@ -935,8 +936,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:
@@ -945,8 +946,8 @@ channels:
autoSelectFamily: false
```
- - Відповіді з діапазону benchmark RFC 2544 (`198.18.0.0/15`) уже типово дозволені
- для завантажень медіа Telegram. Якщо довірена схема fake-IP або
+ - Відповіді з діапазону benchmark RFC 2544 (`198.18.0.0/15`) уже дозволені
+ для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
transparent proxy переписує `api.telegram.org` на якусь іншу
приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете
явно ввімкнути обхід лише для Telegram:
@@ -960,17 +961,14 @@ channels:
- Те саме явне ввімкнення доступне для окремого облікового запису в
`channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`.
- - Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште
- небезпечний прапорець вимкненим. Telegram media вже типово дозволяє діапазон
- benchmark RFC 2544.
+ - Якщо ваш proxy резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште
+ небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяють діапазон benchmark RFC 2544.
- `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
- media від SSRF. Використовуйте це лише в довірених середовищах proxy, що
- контролюються оператором, таких як fake-IP маршрутизація Clash, Mihomo або Surge,
- коли вони синтезують приватні або special-use відповіді поза діапазоном
- benchmark RFC 2544. Для звичайного публічного доступу Telegram через інтернет
- залишайте цей параметр вимкненим.
+ `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист від SSRF для медіа Telegram. Використовуйте це лише в довірених середовищах proxy, контрольованих оператором,
+ таких як маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
+ синтезують приватні або special-use відповіді поза діапазоном benchmark RFC 2544.
+ Для звичайного доступу до Telegram через публічний інтернет залишайте це вимкненим.
- Перевизначення через середовище (тимчасово):
@@ -987,87 +985,87 @@ dig +short api.telegram.org AAAA
-Більше допомоги: [Усунення проблем каналу](/uk/channels/troubleshooting).
+Докладніше: [Усунення проблем каналу](/uk/channels/troubleshooting).
-## Вказівники довідника config Telegram
+## Вказівники на довідник config Telegram
Основний довідник:
- `channels.telegram.enabled`: увімкнути/вимкнути запуск каналу.
- `channels.telegram.botToken`: токен бота (BotFather).
- `channels.telegram.tokenFile`: читати токен зі шляху до звичайного файла. Символічні посилання відхиляються.
-- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (типово: pairing).
-- `channels.telegram.allowFrom`: allowlist для DM (числові ID користувачів Telegram). `allowlist` вимагає принаймні один ID відправника. `open` вимагає `"*"`. `openclaw doctor --fix` може визначити застарілі записи `@username` як ID і може відновити записи allowlist з файлів pairing-store у потоках міграції allowlist.
-- `channels.telegram.actions.poll`: увімкнути або вимкнути створення опитувань Telegram (типово: увімкнено; усе ще потребує `sendMessage`).
-- `channels.telegram.defaultTo`: типова ціль Telegram, яку використовує CLI `--deliver`, коли не вказано явний `--reply-to`.
-- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (типово: allowlist).
-- `channels.telegram.groupAllowFrom`: allowlist відправників у групі (числові ID користувачів Telegram). `openclaw doctor --fix` може визначити застарілі записи `@username` як ID. Нечислові записи ігноруються під час auth. Групова auth не використовує резервний механізм DM pairing-store (`2026.2.25+`).
-- Пріоритетність для кількох облікових записів:
- - Якщо налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію.
- - Якщо не задано жодного з них, OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` видає попередження.
+- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (за замовчуванням: pairing).
+- `channels.telegram.allowFrom`: allowlist для DM (числові ID користувачів Telegram). `allowlist` потребує щонайменше один ID відправника. `open` потребує `"*"`. `openclaw doctor --fix` може перетворювати застарілі записи `@username` на ID і може відновлювати записи allowlist із файлів pairing-store у сценаріях міграції allowlist.
+- `channels.telegram.actions.poll`: увімкнути або вимкнути створення опитувань Telegram (за замовчуванням: увімкнено; все одно потребує `sendMessage`).
+- `channels.telegram.defaultTo`: ціль Telegram за замовчуванням, яку CLI `--deliver` використовує, коли не вказано явний `--reply-to`.
+- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (за замовчуванням: allowlist).
+- `channels.telegram.groupAllowFrom`: allowlist відправників у групах (числові ID користувачів Telegram). `openclaw doctor --fix` може перетворювати застарілі записи `@username` на ID. Нечислові записи ігноруються під час авторизації. Авторизація груп не використовує резервне значення з DM pairing-store (`2026.2.25+`).
+- Пріоритет для кількох облікових записів:
+ - Коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням.
+ - Якщо не задано жодне з них, OpenClaw використовує як резервне значення перший нормалізований ID облікового запису, а `openclaw doctor` показує попередження.
- `channels.telegram.accounts.default.allowFrom` і `channels.telegram.accounts.default.groupAllowFrom` застосовуються лише до облікового запису `default`.
- - Іменовані облікові записи успадковують `channels.telegram.allowFrom` і `channels.telegram.groupAllowFrom`, коли значення на рівні облікового запису не задано.
+ - Іменовані облікові записи успадковують `channels.telegram.allowFrom` і `channels.telegram.groupAllowFrom`, якщо значення на рівні облікового запису не задано.
- Іменовані облікові записи не успадковують `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
-- `channels.telegram.groups`: типові значення для окремих груп + allowlist (використовуйте `"*"` для глобальних типових значень).
+- `channels.telegram.groups`: значення за замовчуванням для групи + allowlist (використовуйте `"*"` для глобальних значень за замовчуванням).
- `channels.telegram.groups..groupPolicy`: перевизначення `groupPolicy` для окремої групи (`open | allowlist | disabled`).
- - `channels.telegram.groups..requireMention`: типове обмеження за згадкою.
- - `channels.telegram.groups..skills`: фільтр Skills (пропущено = усі Skills, порожньо = жодного).
+ - `channels.telegram.groups..requireMention`: типове керування потребою згадки.
+ - `channels.telegram.groups..skills`: фільтр Skills (не вказано = усі Skills, порожньо = жодного).
- `channels.telegram.groups..allowFrom`: перевизначення allowlist відправників для окремої групи.
- `channels.telegram.groups..systemPrompt`: додатковий системний prompt для групи.
- `channels.telegram.groups..enabled`: вимкнути групу, якщо `false`.
- - `channels.telegram.groups..topics..*`: перевизначення для окремої теми (поля групи + `agentId` лише для теми).
- - `channels.telegram.groups..topics..agentId`: маршрутизувати цю тему до конкретного агента (перевизначає маршрутизацію на рівні групи та binding).
+ - `channels.telegram.groups..topics..*`: перевизначення для окремої теми (поля групи + `agentId`, доступний лише для теми).
+ - `channels.telegram.groups..topics..agentId`: маршрутизувати цю тему до конкретного агента (перевизначає маршрутизацію на рівні групи та bindings).
- `channels.telegram.groups..topics..groupPolicy`: перевизначення `groupPolicy` для окремої теми (`open | allowlist | disabled`).
-- `channels.telegram.groups..topics..requireMention`: перевизначення обмеження за згадкою для окремої теми.
-- `bindings[]` верхнього рівня з `type: "acp"` і канонічним ID теми `chatId:topic:topicId` у `match.peer.id`: поля постійного прив’язування тем ACP (див. [ACP Agents](/uk/tools/acp-agents#channel-specific-settings)).
-- `channels.telegram.direct..topics..agentId`: маршрутизувати теми DM до конкретного агента (така сама поведінка, як і для тем форуму).
-- `channels.telegram.execApprovals.enabled`: увімкнути Telegram як чат-клієнт погодження exec для цього облікового запису.
-- `channels.telegram.execApprovals.approvers`: ID користувачів Telegram, яким дозволено погоджувати або відхиляти запити exec. Необов’язково, якщо `channels.telegram.allowFrom` або прямий `channels.telegram.defaultTo` уже визначає власника.
-- `channels.telegram.execApprovals.target`: `dm | channel | both` (типово: `dm`). `channel` і `both` зберігають вихідну тему Telegram, якщо вона є.
-- `channels.telegram.execApprovals.agentFilter`: необов’язковий фільтр ID агента для пересланих запитів на погодження.
-- `channels.telegram.execApprovals.sessionFilter`: необов’язковий фільтр ключа сесії (підрядок або regex) для пересланих запитів на погодження.
-- `channels.telegram.accounts..execApprovals`: перевизначення маршрутизації погоджень exec у Telegram та авторизації затверджувачів для окремого облікового запису.
-- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (типово: allowlist).
+- `channels.telegram.groups..topics..requireMention`: перевизначення потреби згадки для окремої теми.
+- верхньорівневий `bindings[]` з `type: "acp"` і канонічним ID теми `chatId:topic:topicId` у `match.peer.id`: поля постійної прив’язки теми ACP (див. [ACP Agents](/uk/tools/acp-agents#channel-specific-settings)).
+- `channels.telegram.direct..topics..agentId`: маршрутизувати теми DM до конкретного агента (та сама поведінка, що й для тем форуму).
+- `channels.telegram.execApprovals.enabled`: увімкнути Telegram як чат-клієнт підтвердження exec для цього облікового запису.
+- `channels.telegram.execApprovals.approvers`: ID користувачів Telegram, яким дозволено підтверджувати або відхиляти запити exec. Необов’язково, якщо `channels.telegram.allowFrom` або прямий `channels.telegram.defaultTo` вже ідентифікує власника.
+- `channels.telegram.execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). `channel` і `both` зберігають вихідну тему Telegram, якщо вона є.
+- `channels.telegram.execApprovals.agentFilter`: необов’язковий фільтр ID агента для пересланих запитів на підтвердження.
+- `channels.telegram.execApprovals.sessionFilter`: необов’язковий фільтр ключа сесії (підрядок або regex) для пересланих запитів на підтвердження.
+- `channels.telegram.accounts..execApprovals`: перевизначення для окремого облікового запису для маршрутизації підтверджень exec і авторизації осіб, що підтверджують.
+- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (за замовчуванням: allowlist).
- `channels.telegram.accounts..capabilities.inlineButtons`: перевизначення для окремого облікового запису.
- `channels.telegram.commands.nativeSkills`: увімкнути/вимкнути нативні команди Skills у Telegram.
-- `channels.telegram.replyToMode`: `off | first | all` (типово: `off`).
+- `channels.telegram.replyToMode`: `off | first | all` (за замовчуванням: `off`).
- `channels.telegram.textChunkLimit`: розмір вихідного фрагмента (символи).
-- `channels.telegram.chunkMode`: `length` (типово) або `newline`, щоб розбивати за порожніми рядками (межами абзаців) перед розбиттям за довжиною.
-- `channels.telegram.linkPreview`: перемикач попереднього перегляду посилань для вихідних повідомлень (типово: true).
-- `channels.telegram.streaming`: `off | partial | block | progress` (попередній перегляд живого потоку; типово: `partial`; `progress` відповідає `partial`; `block` — сумісність із застарілим режимом попереднього перегляду). Попередній перегляд потоку Telegram використовує одне повідомлення попереднього перегляду, яке редагується на місці.
-- `channels.telegram.mediaMaxMb`: обмеження вхідних/вихідних медіа Telegram (МБ, типово: 100).
-- `channels.telegram.retry`: політика повторних спроб для допоміжних функцій надсилання Telegram (CLI/tools/actions) у разі відновлюваних вихідних помилок API (attempts, minDelayMs, maxDelayMs, jitter).
-- `channels.telegram.network.autoSelectFamily`: перевизначити Node autoSelectFamily (true=увімкнути, false=вимкнути). Типово ввімкнено в Node 22+, а в WSL2 типово вимкнено.
-- `channels.telegram.network.dnsResultOrder`: перевизначити порядок результатів DNS (`ipv4first` або `verbatim`). Типово `ipv4first` у Node 22+.
-- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: небезпечне явне ввімкнення для довірених середовищ fake-IP або transparent proxy, де завантаження медіа Telegram визначають `api.telegram.org` у приватні/внутрішні/special-use адреси поза типовим дозволеним benchmark-діапазоном RFC 2544.
+- `channels.telegram.chunkMode`: `length` (за замовчуванням) або `newline`, щоб ділити за порожніми рядками (межами абзаців) перед поділом за довжиною.
+- `channels.telegram.linkPreview`: перемикач попереднього перегляду посилань для вихідних повідомлень (за замовчуванням: true).
+- `channels.telegram.streaming`: `off | partial | block | progress` (потоковий live preview; за замовчуванням: `partial`; `progress` зіставляється з `partial`; `block` — сумісність із застарілим режимом preview). Потоковий preview у Telegram використовує одне повідомлення preview, яке редагується на місці.
+- `channels.telegram.mediaMaxMb`: обмеження медіа Telegram для вхідних/вихідних даних (МБ, за замовчуванням: 100).
+- `channels.telegram.retry`: політика повторних спроб для допоміжних функцій надсилання Telegram (CLI/tools/actions) у разі відновлюваних вихідних помилок API (`attempts`, `minDelayMs`, `maxDelayMs`, `jitter`).
+- `channels.telegram.network.autoSelectFamily`: перевизначити Node autoSelectFamily (true=увімкнути, false=вимкнути). За замовчуванням увімкнено в Node 22+, а у WSL2 за замовчуванням вимкнено.
+- `channels.telegram.network.dnsResultOrder`: перевизначити порядок результатів DNS (`ipv4first` або `verbatim`). За замовчуванням `ipv4first` у Node 22+.
+- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: небезпечне явне ввімкнення для довірених середовищ fake-IP або transparent-proxy, де завантаження медіа Telegram резолвлять `api.telegram.org` у приватні/внутрішні/special-use адреси поза типовим дозволеним benchmark-діапазоном RFC 2544.
- `channels.telegram.proxy`: URL proxy для викликів Bot API (SOCKS/HTTP).
- `channels.telegram.webhookUrl`: увімкнути режим Webhook (потребує `channels.telegram.webhookSecret`).
- `channels.telegram.webhookSecret`: секрет Webhook (обов’язковий, коли задано webhookUrl).
-- `channels.telegram.webhookPath`: локальний шлях Webhook (типово `/telegram-webhook`).
-- `channels.telegram.webhookHost`: локальний хост прив’язки Webhook (типово `127.0.0.1`).
-- `channels.telegram.webhookPort`: локальний порт прив’язки Webhook (типово `8787`).
-- `channels.telegram.actions.reactions`: керування реакціями інструментів Telegram.
-- `channels.telegram.actions.sendMessage`: керування надсиланням повідомлень інструментами Telegram.
-- `channels.telegram.actions.deleteMessage`: керування видаленням повідомлень інструментами Telegram.
-- `channels.telegram.actions.sticker`: керування діями зі стікерами Telegram — надсилання та пошук (типово: false).
-- `channels.telegram.reactionNotifications`: `off | own | all` — керує, які реакції запускають системні події (типово: `own`, якщо не задано).
-- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — керує можливостями реакцій агента (типово: `minimal`, якщо не задано).
-- `channels.telegram.errorPolicy`: `reply | silent` — керує поведінкою відповіді на помилки (типово: `reply`). Підтримуються перевизначення для окремого облікового запису/групи/теми.
-- `channels.telegram.errorCooldownMs`: мінімальна кількість мс між відповідями з помилками в тому самому чаті (типово: `60000`). Запобігає спаму помилками під час збоїв.
+- `channels.telegram.webhookPath`: локальний шлях Webhook (за замовчуванням `/telegram-webhook`).
+- `channels.telegram.webhookHost`: локальний хост прив’язки Webhook (за замовчуванням `127.0.0.1`).
+- `channels.telegram.webhookPort`: локальний порт прив’язки Webhook (за замовчуванням `8787`).
+- `channels.telegram.actions.reactions`: керувальний перемикач для реакцій інструментів Telegram.
+- `channels.telegram.actions.sendMessage`: керувальний перемикач для надсилання повідомлень інструментами Telegram.
+- `channels.telegram.actions.deleteMessage`: керувальний перемикач для видалення повідомлень інструментами Telegram.
+- `channels.telegram.actions.sticker`: керувальний перемикач для дій зі стікерами Telegram — надсилання та пошук (за замовчуванням: false).
+- `channels.telegram.reactionNotifications`: `off | own | all` — керує тим, які реакції запускають системні події (за замовчуванням: `own`, якщо не задано).
+- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — керує можливістю агента працювати з реакціями (за замовчуванням: `minimal`, якщо не задано).
+- `channels.telegram.errorPolicy`: `reply | silent` — керує поведінкою відповідей з помилками (за замовчуванням: `reply`). Підтримуються перевизначення для окремих облікових записів/груп/тем.
+- `channels.telegram.errorCooldownMs`: мінімальна кількість мс між відповідями з помилками в одному й тому самому чаті (за замовчуванням: `60000`). Запобігає спаму помилками під час збоїв.
- [Довідник конфігурації - Telegram](/uk/gateway/configuration-reference#telegram)
-Telegram-специфічні поля з високим сигналом:
+Специфічні для Telegram поля з високою цінністю сигналу:
-- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
-- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`)
-- погодження exec: `execApprovals`, `accounts.*.execApprovals`
+- запуск/автентифікація: `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`
-- потокове передавання: `streaming` (попередній перегляд), `blockStreaming`
+- потокове виведення: `streaming` (preview), `blockStreaming`
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
-- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
-- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
+- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
+- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- реакції: `reactionNotifications`, `reactionLevel`
- помилки: `errorPolicy`, `errorCooldownMs`
@@ -1075,7 +1073,7 @@ Telegram-специфічні поля з високим сигналом:
## Пов’язане
-- [З’єднання](/uk/channels/pairing)
+- [Сполучення](/uk/channels/pairing)
- [Групи](/uk/channels/groups)
- [Безпека](/uk/gateway/security)
- [Маршрутизація каналів](/uk/channels/channel-routing)
diff --git a/docs/uk/channels/troubleshooting.md b/docs/uk/channels/troubleshooting.md
index 3ec547c80..b455db263 100644
--- a/docs/uk/channels/troubleshooting.md
+++ b/docs/uk/channels/troubleshooting.md
@@ -1,14 +1,14 @@
---
read_when:
- Транспорт каналу показує, що підключено, але відповіді не працюють
- - Перш ніж переходити до детальної документації провайдера, потрібні перевірки, специфічні для каналу
-summary: Швидке усунення несправностей на рівні каналу з ознаками збоїв і виправленнями для кожного каналу
+ - Потрібні перевірки, специфічні для каналу, перед переходом до детальної документації провайдера
+summary: Швидке усунення несправностей на рівні каналу з характерними ознаками збоїв і виправленнями для кожного каналу
title: Усунення несправностей каналу
x-i18n:
- generated_at: "2026-04-20T22:05:51Z"
+ generated_at: "2026-04-21T00:17:12Z"
model: gpt-5.4
provider: openai
- source_hash: 9dd6a0a863b97c984d44d7fd75b3b3cb3b9c4290e2da26e5677e8c4f9700a73c
+ source_hash: 69e9e8f093bee1c7aafc244d6b999a957b7571cc125096d72060d0df52bf52c0
source_path: channels/troubleshooting.md
workflow: 15
---
@@ -19,7 +19,7 @@ x-i18n:
## Послідовність команд
-Спочатку запускайте їх у такому порядку:
+Спочатку виконайте їх у такому порядку:
```bash
openclaw status
@@ -29,73 +29,73 @@ openclaw doctor
openclaw channels status --probe
```
-Базовий стан справної системи:
+Ознаки справного базового стану:
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable` або `admin-capable`
-- Перевірка каналу показує, що транспорт підключений і, де це підтримується, `works` або `audit ok`
+- Перевірка каналу показує, що транспорт підключено і, де підтримується, `works` або `audit ok`
## WhatsApp
-### Ознаки збоїв WhatsApp
+### Характерні ознаки збоїв WhatsApp
| Симптом | Найшвидша перевірка | Виправлення |
| ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| Підключено, але немає відповідей у DM | `openclaw pairing list whatsapp` | Підтвердьте відправника або змініть політику DM/список дозволених. |
-| Повідомлення в групі ігноруються | Перевірте `requireMention` і шаблони згадувань у конфігурації | Згадайте бота або послабте політику згадувань для цієї групи. |
-| Випадкові розриви з'єднання/цикли повторного входу | `openclaw channels status --probe` + журнали | Увійдіть знову і переконайтеся, що каталог облікових даних у справному стані. |
+| Повідомлення групи ігноруються | Перевірте `requireMention` і шаблони згадок у конфігурації | Згадайте бота або пом’якшіть політику згадок для цієї групи. |
+| Випадкові відключення/цикли повторного входу | `openclaw channels status --probe` + журнали | Увійдіть знову та переконайтеся, що каталог облікових даних справний. |
Повне усунення несправностей: [/channels/whatsapp#troubleshooting](/uk/channels/whatsapp#troubleshooting)
## Telegram
-### Ознаки збоїв Telegram
+### Характерні ознаки збоїв Telegram
-| Симптом | Найшвидша перевірка | Виправлення |
-| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
-| Є `/start`, але немає придатного потоку відповідей | `openclaw pairing list telegram` | Підтвердьте сполучення або змініть політику DM. |
-| Бот онлайн, але група мовчить | Перевірте вимогу згадування та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. |
-| Помилки надсилання з мережевими збоями | Перегляньте журнали на предмет збоїв викликів Telegram API | Виправте маршрутизацію DNS/IPv6/проксі до `api.telegram.org`. |
-| Polling зависає або повільно перепідключається | `openclaw logs --follow` для діагностики polling | Оновіться, а потім перевірте проксі/DNS/IPv6, якщо `getUpdates` продовжує завершуватися за тайм-аутом. |
-| `setMyCommands` відхиляється під час запуску | Перегляньте журнали на `BOT_COMMANDS_TOO_MUCH` | Зменште кількість команд Telegram від plugin/Skills/користувацьких команд або вимкніть нативні меню. |
-| Оновилися, і список дозволених вас блокує | `openclaw security audit` і списки дозволених у конфігурації | Запустіть `openclaw doctor --fix` або замініть `@username` на числові ID відправників. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| ----------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| Є `/start`, але немає придатного потоку відповідей | `openclaw pairing list telegram` | Підтвердьте сполучення або змініть політику DM. |
+| Бот онлайн, але група мовчить | Перевірте вимогу згадки та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. |
+| Помилки надсилання з мережевими помилками | Перегляньте журнали на наявність збоїв викликів Telegram API | Виправте маршрутизацію DNS/IPv6/проксі до `api.telegram.org`. |
+| Опитування зависає або повільно перепідключається | `openclaw logs --follow` для діагностики опитування | Оновіться; якщо перезапуски є хибнопозитивними, налаштуйте `pollingStallThresholdMs`. Постійні зависання все ще вказують на проксі/DNS/IPv6. |
+| `setMyCommands` відхиляється під час запуску | Перегляньте журнали на `BOT_COMMANDS_TOO_MUCH` | Зменште кількість команд Telegram для Plugin/Skills/користувацьких команд або вимкніть нативні меню. |
+| Після оновлення список дозволених вас блокує | `openclaw security audit` і списки дозволених у конфігурації | Виконайте `openclaw doctor --fix` або замініть `@username` на числові ID відправників. |
Повне усунення несправностей: [/channels/telegram#troubleshooting](/uk/channels/telegram#troubleshooting)
## Discord
-### Ознаки збоїв Discord
+### Характерні ознаки збоїв Discord
-| Симптом | Найшвидша перевірка | Виправлення |
-| ------------------------------- | ------------------------------------ | -------------------------------------------------------------- |
-| Бот онлайн, але немає відповідей у guild | `openclaw channels status --probe` | Дозвольте guild/channel і перевірте intent для вмісту повідомлень. |
-| Повідомлення в групі ігноруються | Перевірте журнали на drops через gating згадувань | Згадайте бота або встановіть `requireMention: false` для guild/channel. |
-| Немає відповідей у DM | `openclaw pairing list discord` | Підтвердьте DM pairing або скоригуйте політику DM. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| ------------------------------- | -------------------------------- | ------------------------------------------------------------- |
+| Бот онлайн, але немає відповідей у guild | `openclaw channels status --probe` | Дозвольте guild/channel і перевірте intent вмісту повідомлень. |
+| Повідомлення групи ігноруються | Перевірте журнали на відкидання через вимогу згадки | Згадайте бота або встановіть `requireMention: false` для guild/channel. |
+| Відсутні відповіді в DM | `openclaw pairing list discord` | Підтвердьте сполучення DM або скоригуйте політику DM. |
Повне усунення несправностей: [/channels/discord#troubleshooting](/uk/channels/discord#troubleshooting)
## Slack
-### Ознаки збоїв Slack
+### Характерні ознаки збоїв Slack
-| Симптом | Найшвидша перевірка | Виправлення |
-| -------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Socket mode підключений, але немає відповідей | `openclaw channels status --probe` | Перевірте токен застосунку, токен бота і потрібні scope; зверніть увагу на `botTokenStatus` / `appTokenStatus = configured_unavailable` у конфігураціях на основі SecretRef. |
-| DM заблоковані | `openclaw pairing list slack` | Підтвердьте pairing або послабте політику DM. |
-| Повідомлення в каналі ігнорується | Перевірте `groupPolicy` і список дозволених каналів | Дозвольте канал або перемкніть політику на `open`. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| -------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Socket mode підключено, але немає відповідей | `openclaw channels status --probe` | Перевірте токен застосунку, токен бота та потрібні області доступу; звертайте увагу на `botTokenStatus` / `appTokenStatus = configured_unavailable` у конфігураціях на основі SecretRef. |
+| DM заблоковані | `openclaw pairing list slack` | Підтвердьте сполучення або пом’якшіть політику DM. |
+| Повідомлення каналу ігноруються | Перевірте `groupPolicy` і список дозволених каналів | Дозвольте канал або змініть політику на `open`. |
Повне усунення несправностей: [/channels/slack#troubleshooting](/uk/channels/slack#troubleshooting)
-## iMessage і BlueBubbles
+## iMessage and BlueBubbles
-### Ознаки збоїв iMessage і BlueBubbles
+### Характерні ознаки збоїв iMessage and BlueBubbles
-| Симптом | Найшвидша перевірка | Виправлення |
-| -------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
-| Немає вхідних подій | Перевірте доступність Webhook/сервера і дозволи застосунку | Виправте URL Webhook або стан сервера BlueBubbles. |
-| Можна надсилати, але немає отримання на macOS | Перевірте дозволи macOS privacy для автоматизації Messages | Повторно надайте дозволи TCC і перезапустіть процес каналу. |
-| Відправника DM заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Підтвердьте pairing або оновіть список дозволених. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| -------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
+| Немає вхідних подій | Перевірте доступність Webhook/сервера та дозволи застосунку | Виправте URL Webhook або стан сервера BlueBubbles. |
+| Можна надсилати, але немає прийому на macOS | Перевірте дозволи приватності macOS для автоматизації Messages | Повторно надайте дозволи TCC і перезапустіть процес каналу. |
+| Відправника DM заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Підтвердьте сполучення або оновіть список дозволених. |
Повне усунення несправностей:
@@ -104,39 +104,39 @@ openclaw channels status --probe
## Signal
-### Ознаки збоїв Signal
+### Характерні ознаки збоїв Signal
-| Симптом | Найшвидша перевірка | Виправлення |
-| ------------------------------- | --------------------------------------- | -------------------------------------------------------- |
-| Daemon доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/account daemon `signal-cli` і режим receive. |
-| DM заблоковано | `openclaw pairing list signal` | Підтвердьте відправника або скоригуйте політику DM. |
-| Відповіді в групі не спрацьовують | Перевірте список дозволених груп і шаблони згадувань | Додайте відправника/групу або послабте gating. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| ------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
+| Демон доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/обліковий запис демона `signal-cli` і режим receive. |
+| DM заблоковано | `openclaw pairing list signal` | Підтвердьте відправника або скоригуйте політику DM. |
+| Не спрацьовують відповіді в групі | Перевірте список дозволених груп і шаблони згадок | Додайте відправника/групу або послабте обмеження. |
Повне усунення несправностей: [/channels/signal#troubleshooting](/uk/channels/signal#troubleshooting)
## QQ Bot
-### Ознаки збоїв QQ Bot
+### Характерні ознаки збоїв QQ Bot
-| Симптом | Найшвидша перевірка | Виправлення |
-| ------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
-| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у конфігурації | Встановіть облікові дані або перезапустіть Gateway. |
-| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. |
-| Голос не транскрибується | Перевірте конфігурацію провайдера STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. |
-| Ініційовані ботом повідомлення не надходять | Перевірте вимоги платформи QQ до взаємодії | QQ може блокувати повідомлення, ініційовані ботом, без нещодавньої взаємодії. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| ------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- |
+| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у конфігурації | Задайте облікові дані або перезапустіть Gateway. |
+| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. |
+| Голос не транскрибується | Перевірте конфігурацію провайдера STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. |
+| Ініційовані ботом повідомлення не надходять | Перевірте вимоги QQ platform до взаємодій | QQ може блокувати ініційовані ботом повідомлення без недавньої взаємодії. |
Повне усунення несправностей: [/channels/qqbot#troubleshooting](/uk/channels/qqbot#troubleshooting)
## Matrix
-### Ознаки збоїв Matrix
+### Характерні ознаки збоїв Matrix
-| Симптом | Найшвидша перевірка | Виправлення |
-| ----------------------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
-| Виконано вхід, але повідомлення кімнати ігноруються | `openclaw channels status --probe` | Перевірте `groupPolicy`, список дозволених кімнат і gating згадувань. |
-| DM не обробляються | `openclaw pairing list matrix` | Підтвердьте відправника або скоригуйте політику DM. |
-| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно верифікуйте пристрій, потім перевірте `openclaw matrix verify backup status`. |
-| Відновлення резервної копії очікує/пошкоджене | `openclaw matrix verify backup status` | Запустіть `openclaw matrix verify backup restore` або повторіть із ключем відновлення. |
-| Cross-signing/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | Виправте secret storage, cross-signing і стан резервної копії за один прохід. |
+| Симптом | Найшвидша перевірка | Виправлення |
+| ----------------------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| Вхід виконано, але повідомлення кімнати ігноруються | `openclaw channels status --probe` | Перевірте `groupPolicy`, список дозволених кімнат і обмеження на згадки. |
+| DM не обробляються | `openclaw pairing list matrix` | Підтвердьте відправника або скоригуйте політику DM. |
+| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно верифікуйте пристрій, а потім перевірте `openclaw matrix verify backup status`. |
+| Відновлення резервної копії очікує/пошкоджене | `openclaw matrix verify backup status` | Виконайте `openclaw matrix verify backup restore` або повторіть із ключем відновлення. |
+| Кроспідписування/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | За один прохід виправте secret storage, кроспідписування та стан резервних копій. |
-Повне налаштування і конфігурація: [Matrix](/uk/channels/matrix)
+Повне налаштування та конфігурація: [Matrix](/uk/channels/matrix)