--- read_when: - Працюєте над функціями Telegram або Webhook'ами summary: Стан підтримки, можливості та конфігурація бота Telegram title: Telegram x-i18n: generated_at: "2026-07-03T17:39:02Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 202d6eaaf9348203855659d30616368995bce9269082e60dfed67c8d444abf18 source_path: channels/telegram.md workflow: 16 --- Готово до продакшену для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим webhook необов’язковий. Типова політика DM для Telegram — сполучення. Діагностика та інструкції з відновлення для різних каналів. Повні шаблони й приклади конфігурації каналів. ## Швидке налаштування Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). Запустіть `/newbot`, дотримуйтесь підказок і збережіть токен. ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` Коди сполучення спливають через 1 годину. Додайте бота до своєї групи, а потім отримайте обидва ID, потрібні для доступу групи: - ваш Telegram user ID, що використовується в `allowFrom` / `groupAllowFrom` - Telegram group chat ID, що використовується як ключ у `channels.telegram.groups` Для першого налаштування отримайте group chat ID з `openclaw logs --follow`, бота для пересланих ID або Bot API `getUpdates`. Після того як групу дозволено, `/whoami@` може підтвердити ID користувача й групи. Від’ємні Telegram supergroup IDs, що починаються з `-100`, є group chat IDs. Розміщуйте їх у `channels.telegram.groups`, а не в `groupAllowFrom`. Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. Після успішного запуску OpenClaw кешує ідентичність бота в каталозі стану на строк до 24 годин, щоб перезапуски могли уникнути додаткового виклику Telegram `getMe`; зміна або видалення токена очищає цей кеш. ## Налаштування на стороні Telegram Telegram боти за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. Якщо бот має бачити всі групові повідомлення, виконайте одне з такого: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. Під час перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. Статус адміністратора контролюється в налаштуваннях групи Telegram. Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. - `/setjoingroups` для дозволу/заборони додавання до груп - `/setprivacy` для поведінки видимості в групах ## Контроль доступу й активація ### Ідентичність групового бота У групах Telegram і темах форумів явна згадка налаштованого handle бота (наприклад, `@my_bot`) вважається зверненням до вибраного агента OpenClaw, навіть якщо ім’я персони агента відрізняється від імені користувача Telegram. Політика мовчання групи все ще застосовується до не пов’язаного групового трафіку, але сам handle бота не вважається "кимось іншим". `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - `pairing` (за замовчуванням) - `allowlist` (потрібен принаймні один sender ID у `allowFrom`) - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` `dmPolicy: "open"` з `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими user IDs. `channels.telegram.allowFrom` приймає числові Telegram user IDs. Префікси `telegram:` / `tg:` приймаються й нормалізуються. У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття все ще не містить явний wildcard. `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється під час валідації config. Налаштування запитує лише числові user IDs. Якщо ви оновилися й ваша config містить записи allowlist `@username`, запустіть `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен Telegram бота). Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була довговічною в config (замість залежності від попередніх схвалень сполучення). Поширена плутанина: схвалення сполучення DM не означає "цей відправник авторизований всюди". Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення exec мали явний обліковий запис оператора. Авторизація відправника в групі все ще походить з явних allowlists у config. Якщо ви хочете "я авторизований один раз, і працюють як DM, так і групові команди", помістіть свій числовий Telegram user ID у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій Telegram user ID Безпечніше (без стороннього бота): 1. Напишіть DM своєму боту. 2. Запустіть `openclaw logs --follow`. 3. Прочитайте `from.id`. Офіційний метод Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`. Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає config `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки group-ID - з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи `groups` (або `"*"`) - `groups` налаштовано: діє як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (за замовчуванням) - `disabled` `groupAllowFrom` використовується для фільтрації відправників у групі. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими Telegram user IDs (префікси `telegram:` / `tg:` нормалізуються). Не розміщуйте Telegram group або supergroup chat IDs у `groupAllowFrom`. Від’ємні chat IDs належать до `channels.telegram.groups`. Нечислові записи ігноруються для авторизації відправника. Межа безпеки (`2026.2.25+`): auth відправника в групі **не** успадковує схвалення зі сховища сполучень DM. Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для групи/теми. Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень. Практичний шаблон для ботів з одним власником: задайте свій user ID у `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Налаштування групи лише для власника: ```json5 { channels: { telegram: { enabled: true, dmPolicy: "pairing", allowFrom: [""], groupPolicy: "allowlist", groups: { "": { requireMention: true, }, }, }, }, } ``` Перевірте це з групи за допомогою `@ ping`. Звичайні групові повідомлення не запускають бота, поки `requireMention: true`. Приклад: дозволити будь-якому учаснику в одній конкретній групі: ```json5 { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` Приклад: дозволити лише конкретних користувачів всередині однієї конкретної групи: ```json5 { channels: { telegram: { groups: { "-1001234567890": { requireMention: true, allowFrom: ["8734062810", "745123456"], }, }, }, }, } ``` Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. - Розміщуйте від’ємні Telegram group або supergroup chat IDs на кшталт `-1001234567890` у `channels.telegram.groups`. - Розміщуйте Telegram user IDs на кшталт `8734062810` у `groupAllowFrom`, коли хочете обмежити, хто всередині дозволеної групи може запускати бота. - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. Групові відповіді за замовчуванням потребують згадки. Згадка може надходити з: - нативної згадки `@botusername`, або - шаблонів згадок у: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` Перемикачі команд рівня сесії: - `/activation always` - `/activation mention` Вони оновлюють лише стан сесії. Використовуйте config для постійності. Приклад постійної config: ```json5 { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` Контекст історії групи завжди ввімкнений для груп і обмежений `historyLimit`. Задайте `channels.telegram.historyLimit: 0`, щоб вимкнути вікно історії групи Telegram. Застарілий ключ `includeGroupHistoryContext` видаляється командою `openclaw doctor --fix`. Отримання group chat ID: - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` - або прочитайте `chat.id` з `openclaw logs --follow` - або перегляньте Bot API `getUpdates` - після того як групу дозволено, запустіть `/whoami@`, якщо нативні команди ввімкнені ## Поведінка runtime - Telegram належить процесу Gateway. - Маршрутизація детермінована: вхідні відповіді Telegram повертаються в Telegram (модель не вибирає канали). - Вхідні повідомлення нормалізуються у спільний конверт каналу з метаданими відповіді, заповнювачами медіа та збереженим контекстом ланцюжка відповідей для відповідей Telegram, які спостерігав Gateway. - Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:`, щоб ізолювати теми. - Повідомлення DM можуть містити `message_thread_id`; OpenClaw зберігає його для відповідей. Сеанси тем DM розділяються лише тоді, коли Telegram `getMe` повідомляє `has_topics_enabled: true` для бота; інакше DM залишаються у пласкому сеансі. - Довге опитування використовує grammY runner із послідовністю на рівні чату/потоку. Загальна паралельність приймача runner використовує `agents.defaults.maxConcurrent`. - Запуск кількох облікових записів обмежує паралельні перевірки Telegram `getMe`, щоб великі парки ботів не запускали перевірки всіх облікових записів одночасно. - Довге опитування захищене всередині кожного процесу Gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший Gateway OpenClaw, скрипт або зовнішній poller. - Перезапуски сторожового таймера довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зависання опитування під час тривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. - Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується). `channels.telegram.dm.threadReplies` і `channels.telegram.direct..threadReplies` було вилучено. Запустіть `openclaw doctor --fix` після оновлення, якщо ваша конфігурація все ще містить ці ключі. Маршрутизація тем DM тепер залежить від можливості бота з Telegram `getMe.has_topics_enabled`, якою керує режим потоків BotFather: боти з увімкненими темами використовують сеанси DM, обмежені потоком, коли Telegram надсилає `message_thread_id`; інші DM залишаються у пласкому сеансі. ## Довідник функцій OpenClaw може транслювати часткові відповіді в реальному часі: - прямі чати: повідомлення попереднього перегляду + `editMessageText` - групи/теми: повідомлення попереднього перегляду + `editMessageText` Вимога: - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - короткі початкові попередні перегляди відповідей дебаунсяться, а потім матеріалізуються після обмеженої затримки, якщо запуск усе ще активний - `progress` зберігає один редагований чернетковий статус для прогресу інструментів, показує стабільну мітку статусу, коли активність відповіді надходить до прогресу інструментів, очищає її після завершення та надсилає фінальну відповідь як звичайне повідомлення - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна трансляція попереднього перегляду) - `streaming.preview.commandText` керує деталями команд/exec у цих рядках прогресу інструментів: `raw` (за замовчуванням, зберігає випущену поведінку) або `status` (лише мітка інструмента) - `streaming.progress.commentary` (за замовчуванням: `false`) вмикає текст коментаря/преамбули асистента в тимчасовій чернетці прогресу - застарілі `channels.telegram.streamMode`, булеві значення `streaming` і вилучені ключі власного попереднього перегляду чернеток виявляються; запустіть `openclaw doctor --fix`, щоб мігрувати їх до поточної конфігурації streaming Оновлення попереднього перегляду прогресу інструментів — це короткі рядки статусу, які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення плану, підсумки патчів або текст преамбули/коментаря Codex у режимі сервера застосунку Codex. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніших версій. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` Щоб залишити прогрес інструментів видимим, але приховати текст команд/exec, задайте: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` Використовуйте режим `progress`, коли потрібен видимий прогрес інструментів без редагування фінальної відповіді в те саме повідомлення. Розмістіть політику тексту команд у `streaming.progress`: ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` Використовуйте `streaming.mode: "off"` лише коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальний шум інструментів/прогресу приглушується замість надсилання окремими статусними повідомленнями. Запити на схвалення, медіа-навантаження та помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховавши статусні рядки прогресу інструментів. Вибрані відповіді на цитати Telegram є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить вибраний текст цитати, OpenClaw надсилає фінальну відповідь через власний шлях відповіді-цитати Telegram замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показати короткі рядки статусу для цього ходу. Відповіді на поточне повідомлення без вибраного тексту цитати все ще зберігають трансляцію попереднього перегляду. Задайте `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за власні відповіді-цитати, або задайте `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс. Для текстових відповідей: - короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці - довгі фінальні тексти, які розбиваються на кілька повідомлень Telegram, за можливості повторно використовують наявний попередній перегляд як перший фінальний фрагмент, а потім надсилають лише решту фрагментів - фінальні відповіді в режимі progress очищають чернетковий статус і використовують звичайну фінальну доставку замість редагування чернетки у відповідь - якщо фінальне редагування не вдається до підтвердження завершеного тексту, OpenClaw використовує звичайну фінальну доставку та очищає застарілий попередній перегляд Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. Трансляція попереднього перегляду відокремлена від блочної трансляції. Коли блочну трансляцію явно ввімкнено для Telegram, OpenClaw пропускає трансляцію попереднього перегляду, щоб уникнути подвійної трансляції. Поведінка трансляції reasoning: - `/reasoning stream` використовує шлях попереднього перегляду reasoning підтримуваного каналу; у Telegram він транслює reasoning у живий попередній перегляд під час генерації - попередній перегляд reasoning видаляється після фінальної доставки; використовуйте `/reasoning on`, коли reasoning має залишатися видимим - фінальна відповідь надсилається без тексту reasoning Вихідний текст за замовчуванням використовує стандартні HTML-повідомлення Telegram, щоб відповіді залишалися читабельними в поточних клієнтах Telegram. Цей режим сумісності підтримує звичайний жирний текст, курсив, посилання, код, спойлери та цитати, але не підтримує блоки Bot API 10.1, доступні лише в розширеному форматі, як-от власні таблиці, details, rich media та формули. Задайте `channels.telegram.richMessages: true`, щоб увімкнути розширені повідомлення Bot API 10.1: ```json5 { channels: { telegram: { richMessages: true, }, }, } ``` Коли ввімкнено: - Агенту повідомляється, що розширені повідомлення Telegram доступні для цього бота/облікового запису. - Текст Markdown рендериться через Markdown IR OpenClaw і надсилається як розширений HTML Telegram. - Явні розширені HTML-навантаження зберігають підтримувані теги Bot API 10.1, як-от заголовки, таблиці, details, rich media та формули. - Підписи до медіа все ще використовують HTML-підписи Telegram, бо розширені повідомлення не замінюють підписи. Це тримає текст моделі подалі від сигілів Telegram Rich Markdown, тож валюта на кшталт `$400-600K` не парситься як математика. Довгий розширений текст автоматично розбивається відповідно до обмежень Telegram для розширеного тексту та розширених блоків. Таблиці, що перевищують ліміт колонок Telegram, надсилаються як блоки коду. За замовчуванням: вимкнено для сумісності клієнтів. Розширені повідомлення потребують сумісних клієнтів Telegram; деякі поточні клієнти Desktop, Web, Android і сторонні клієнти показують прийняті розширені повідомлення як непідтримувані. Залишайте цю опцію вимкненою, якщо не кожен клієнт, який використовується з ботом, може їх рендерити. `/status` показує, чи ввімкнено розширені повідомлення для поточного сеансу Telegram. Попередні перегляди посилань увімкнено за замовчуванням. `channels.telegram.linkPreview: false` пропускає автоматичне виявлення сутностей для розширеного тексту. Реєстрація меню команд Telegram обробляється під час запуску за допомогою `setMyCommands`. Стандартні параметри власних команд: - `commands.native: "auto"` вмикає власні команди для Telegram Додайте користувацькі записи меню команд: ```json5 { channels: { telegram: { customCommands: [ { command: "backup", description: "Git backup" }, { command: "generate", description: "Create an image" }, ], }, }, } ``` Правила: - імена нормалізуються (видаляється початковий `/`, приводяться до нижнього регістру) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - користувацькі команди не можуть перевизначати власні команди - конфлікти/дублікати пропускаються та записуються в журнал Примітки: - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - команди Plugin/Skills усе ще можуть працювати, коли їх вводять, навіть якщо вони не показані в меню Telegram Якщо власні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть усе ще реєструватися, якщо це налаштовано. Поширені помилки налаштування: - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `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 зупиняється до опитування, тому це не повідомляється як помилка очищення Webhook. - `setMyCommands failed` з мережевими/fetch-помилками зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. ### Команди сполучення пристрою (`device-pair` Plugin) Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS 3. `/pair pending` перелічує очікувані запити (включно з роллю/областями дії) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один очікуваний запит - `/pair approve latest` для найновішого Код налаштування містить короткоживучий bootstrap-токен. Вбудований bootstrap коду налаштування повертає довготривалий токен вузла з `scopes: []` плюс обмежений токен передавання оператору для довіреного мобільного onboarding. Цей токен оператора може читати власну конфігурацію часу налаштування, але не надає областей дії мутації сполучення або `operator.admin`. Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роллю/областями дії/публічним ключем), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно запустіть `/pair pending` перед схваленням. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). Налаштуйте область дії вбудованої клавіатури: ```json5 { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` Перевизначення для окремого облікового запису: ```json5 { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` Області дії: - `off` - `dm` - `group` - `all` - `allowlist` (за замовчуванням) Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. Приклад дії повідомлення: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "Choose an option:", buttons: [ [ { text: "Yes", callback_data: "yes" }, { text: "No", callback_data: "no" }, ], [{ text: "Cancel", callback_data: "cancel" }], ], } ``` Приклад кнопки Mini App: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "Open app:", presentation: { blocks: [ { type: "buttons", buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }], }, ], }, } ``` Кнопки Telegram `web_app` працюють лише в приватних чатах між користувачем і ботом. Натискання callback, які не обробляє зареєстрований інтерактивний обробник plugin, передаються агенту як текст: `callback_data: ` Дії інструментів Telegram включають: - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content` або `caption`, необов’язкові вбудовані кнопки `presentation`; редагування лише кнопок оновлює розмітку відповіді) - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) Дії повідомлень каналу надають ергономічні псевдоніми (`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 для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) Telegram підтримує явні теги гілкування відповідей у згенерованому виводі: - `[[reply_to_current]]` відповідає на повідомлення, що ініціювало дію - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: - `off` (за замовчуванням) - `first` - `all` Коли гілкування відповідей увімкнене й доступний оригінальний текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й переходять до звичайної відповіді, якщо Telegram відхиляє цитату. Примітка: `off` вимикає неявне гілкування відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. Форумні супергрупи: - ключі сесій теми додають `:topic:` - відповіді й індикатор набору спрямовуються в гілку теми - шлях конфігурації теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - надсилання повідомлень пропускають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - дії індикатора набору все одно включають `message_thread_id` Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` застосовується лише до теми й не успадковується з типових налаштувань групи. `topics."*"` задає типові налаштування для кожної теми в цій групі; точні ID тем усе одно мають пріоритет над `"*"`. **Маршрутизація агентів за темами**: Кожна тема може маршрутизуватися до іншого агента, якщо задати `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { channels: { telegram: { groups: { "-1001234567890": { topics: { "1": { agentId: "main" }, // General topic → main agent "3": { agentId: "zu" }, // Dev topic → zu agent "5": { agentId: "coder" } // Code review → coder agent } } } } } } ``` Після цього кожна тема має власний ключ сесії: `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 spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишався ввімкненим (за замовчуванням: `true`). Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають метадані відповіді; вони використовують ключі сесій з урахуванням гілок лише тоді, коли Telegram `getMe` повідомляє `has_topics_enabled: true` для бота. Колишні перевизначення `dm.threadReplies` і `direct.*.threadReplies` навмисно вилучено; використовуйте режим гілок BotFather як єдине джерело істини й виконайте `openclaw doctor --fix`, щоб видалити застарілі ключі конфігурації. ### Аудіоповідомлення Telegram розрізняє голосові нотатки та аудіофайли. - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосову нотатку - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий транскрипт, тому голосові повідомлення, обмежені згадками, продовжують працювати. Приклад дії повідомлення: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### Відеоповідомлення Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо. ### Стікери Обробка вхідних стікерів: - статичний WEBP: завантажується й обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається Поля контексту стікера: - `Sticker.emoji` - `Sticker.setName` - `Sticker.fileId` - `Sticker.fileUniqueId` - `Sticker.cachedDescription` Описи стікерів кешуються у стані Plugin OpenClaw SQLite, щоб зменшити кількість повторних викликів зору. Увімкнути дії зі стікерами: ```json5 { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` Дія надсилання стікера: ```json5 { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` Пошук кешованих стікерів: ```json5 { action: "sticker-search", channel: "telegram", query: "cat waving", limit: 5, } ``` Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень). Коли це ввімкнено, 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`) Примітки: - `own` означає лише реакції користувача на повідомлення, надіслані ботом (за можливості через кеш надісланих повідомлень). - Події реакцій усе одно дотримуються засобів контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - Telegram не надає ідентифікатори потоків в оновленнях реакцій. - групи без форуму маршрутизуються до сеансу групового чату - форумні групи маршрутизуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми `allowed_updates` для polling/webhook автоматично містить `message_reaction`. `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. `ackReactionScope` визначає, *коли* цей емодзі фактично надсилається. **Порядок визначення емодзі (`ackReaction`):** - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - Telegram очікує unicode-емодзі (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. **Область дії (`messages.ackReactionScope`):** Провайдер Telegram читає область дії з `messages.ackReactionScope` (типово `"group-mentions"`). Наразі немає перевизначення на рівні облікового запису Telegram або каналу Telegram. Значення: `"all"` (DM + групи), `"direct"` (лише DM), `"group-all"` (кожне групове повідомлення, без DM), `"group-mentions"` (групи, коли згадано бота; **без DM** — це типове значення), `"off"` / `"none"` (вимкнено). Типова область дії (`"group-mentions"`) не запускає реакції підтвердження в прямих повідомленнях. Щоб отримувати реакцію підтвердження на вхідні DM Telegram, установіть `messages.ackReactionScope` на `"direct"` або `"all"`. Значення зчитується під час запуску провайдера Telegram, тому для набуття зміною чинності потрібен перезапуск gateway. Записи конфігурації каналу ввімкнені типово (`configWrites !== false`). Записи, ініційовані Telegram, включають: - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - `/config set` і `/config unset` (потребує ввімкнення команд) Вимкнути: ```json5 { channels: { telegram: { configWrites: false, }, }, } ``` Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). У режимі long-polling OpenClaw зберігає свій маркер перезапуску лише після успішного передавання оновлення. Якщо обробник завершується з помилкою, це оновлення лишається доступним для повторної спроби в тому самому процесі й не записується як завершене для дедуплікації після перезапуску. Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. Режим Webhook перевіряє запобіжники запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, які використовуються long polling, тому повільні ходи агента не затримують ACK доставки Telegram. - Стандартне значення `channels.telegram.textChunkLimit` — 4000. - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - `channels.telegram.mediaMaxMb` (стандартно 100) обмежує розмір вхідних і вихідних медіа Telegram. - `channels.telegram.mediaGroupFlushMs` (стандартно 500) керує тим, як довго альбоми/групи медіа Telegram буферизуються, перш ніж OpenClaw передасть їх як одне вхідне повідомлення. Збільште значення, якщо частини альбому надходять із запізненням; зменште його, щоб скоротити затримку відповіді на альбом. - `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` вимикає. - додатковий контекст відповіді/цитати/пересилання нормалізується в одне вибране вікно контексту розмови, коли Gateway спостерігав батьківські повідомлення; кеш спостережених повідомлень зберігається у стані Plugin SQLite OpenClaw, а `openclaw doctor --fix` імпортує застарілі sidecar-файли. Telegram включає в оновлення лише один поверхневий `reply_to_message`, тому ланцюжки, старші за кеш, обмежені поточним payload оновлення Telegram. - списки дозволених Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - елементи керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - конфігурація `channels.telegram.retry` застосовується до помічників надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставлення фінальної відповіді для вхідних повідомлень також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві обгортки після надсилання, які можуть дублювати видимі повідомлення. Цілі надсилання CLI та інструментів повідомлень можуть бути числовим ID чату, іменем користувача або ціллю теми форуму: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic" ``` Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму: ```bash openclaw message poll --channel telegram --target 123456789 \ --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ --poll-duration-seconds 300 --poll-public ``` Прапорці опитувань лише для Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) Надсилання Telegram також підтримує: - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплене доставлення, коли бот може закріплювати в цьому чаті - `--force-document`, щоб надсилати вихідні зображення, GIF і відео як документи замість стиснених фото, анімованих медіа або відеозавантажень Обмеження дій: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими Telegram підтримує схвалення exec у DM схвалювачів і може додатково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна розв’язати принаймні одного схвалювача) - `channels.telegram.execApprovals.approvers` (відступає до числових ID власників із `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (стандартно) | `channel` | `both` - `agentFilter`, `sessionFilter` `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може спілкуватися з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене поєднання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`. Доставлення в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Схвалення exec стандартно спливають через 30 хвилин. Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` розв’язуються через схвалення Plugin; інші спочатку розв’язуються через схвалення exec. Див. [Схвалення exec](/uk/tools/exec-approvals). ## Елементи керування відповідями про помилки Коли агент стикається з помилкою доставлення або провайдера, політика помилок керує тим, чи надсилаються повідомлення про помилки в чат Telegram: | Ключ | Значення | Стандартно | Опис | | ----------------------------------- | -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `always`, `once`, `silent` | `always` | `always` — надсилати кожне повідомлення про помилку в чат. `once` — надсилати кожне унікальне повідомлення про помилку один раз за вікно охолодження (пригнічувати повторювані ідентичні помилки). `silent` — ніколи не надсилати повідомлення про помилки в чат. | | `channels.telegram.errorCooldownMs` | число (мс) | `14400000` (4 год) | Вікно охолодження для політики `once`. Після надсилання помилки те саме повідомлення про помилку пригнічується, доки не мине цей інтервал. Запобігає спаму помилками під час збоїв. | Підтримуються перевизначення для кожного облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram). ```json5 { channels: { telegram: { errorPolicy: "always", errorCooldownMs: 120000, groups: { "-1001234567890": { errorPolicy: "silent", // suppress errors in this group }, }, }, }, } ``` ## Усунення несправностей - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - швидкий тест сесії: `/activation always`. - коли існує `channels.telegram.groups`, групу має бути вказано (або включено `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - авторизуйте ідентичність відправника (поєднання та/або числовий `allowFrom`) - авторизація команд усе ще застосовується, навіть коли політика групи — `open` - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню - стартові виклики `deleteMyCommands` / `setMyCommands` і виклики набору `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. - Node 22+ + користувацький fetch/proxy може спричинити негайну поведінку переривання, якщо типи AbortSignal не збігаються. - Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API. - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки. - Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, щоб runner не потребував другого `getMe` перед першим `getUpdates`. - Якщо `deleteWebhook` завершується збоєм через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до довгого опитування замість ще одного керівного виклику до опитування. Досі активний webhook проявляється як конфлікт `getUpdates`; OpenClaw тоді перебудовує транспорт Telegram і повторює очищення webhook. - Якщо сокети 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 також враховує env proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища, а стандартний env proxy відсутній, Telegram також використовує цю URL-адресу для транспорту Bot API. - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: telegram: 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, примусово задайте вибір сімейства: ```yaml channels: telegram: network: autoSelectFamily: false ``` - Відповіді з діапазону тестування RFC 2544 (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або прозорий проксі переписує `api.telegram.org` на якусь іншу приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете увімкнути обхід лише для Telegram: ```yaml channels: telegram: network: dangerouslyAllowPrivateNetwork: true ``` - Таке саме увімкнення доступне для окремого облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Якщо ваш проксі розв'язує медіахости Telegram у `198.18.x.x`, спочатку залиште небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон тестування RFC 2544 за замовчуванням. `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram від SSRF. Використовуйте це лише для довірених середовищ проксі під контролем оператора, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони синтезують приватні або спеціального призначення відповіді поза діапазоном тестування RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. - Перевизначення середовища (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - Перевірте відповіді DNS: ```bash dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` Додаткова довідка: [Усунення проблем із каналами](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) - контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) - типові значення тем: `groups..topics."*"` застосовується до форумних тем без збігу; точні ID тем мають перевагу - підтвердження виконання: `execApprovals`, `accounts.*.execApprovals` - команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode` - потокова передача: `streaming` (попередня версія), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `richMessages`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` - записи/історія: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити типову маршрутизацію явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане Сполучіть користувача Telegram із Gateway. Поведінка списку дозволених груп і тем. Маршрутизуйте вхідні повідомлення до агентів. Модель загроз і посилення захисту. Зіставляйте групи й теми з агентами. Діагностика між каналами.