Telegram

Для ботів Telegram типовим є Privacy Mode, який обмежує перелік отримуваних ними групових повідомлень.

Щоб бачити всі групові повідомлення:

• вимкніть режим конфіденційності через /setprivacy або
• призначте бота адміністратором групи.

Після перемикання режиму конфіденційності видаліть і повторно додайте бота до кожної групи, щоб Telegram застосував зміну.

Статус адміністратора контролюється в налаштуваннях групи Telegram. Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі.

• /setjoingroups — дозволити або заборонити додавання до груп
• /setprivacy — поведінка видимості в групах

Ці самі налаштування доступні у вебзастосунку BotFather, якщо інтерфейс зручніший за команди чату.

OpenClaw транслює часткові відповіді в реальному часі в особистих чатах, групах і темах: надсилає повідомлення попереднього перегляду, потім багаторазово виконує editMessageText, завершуючи його на місці.

• channels.telegram.streaming має значення off | partial | block | progress (за замовчуванням: partial)
• короткі початкові попередні перегляди відповіді обробляються із затримкою, а потім створюються після обмеженого часу очікування, якщо виконання все ще активне
• progress зберігає одну редаговану чернетку стану для перебігу роботи інструментів, показує стабільну мітку стану, коли активність відповіді з’являється раніше за перебіг роботи інструментів, очищає її після завершення та надсилає остаточну відповідь як звичайне повідомлення
• streaming.preview.toolProgress визначає, чи оновлення інструментів і перебігу роботи повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: true, коли потоковий попередній перегляд активний)
• streaming.preview.commandText визначає деталізацію команд і виконання в цих рядках: raw (за замовчуванням) або status (лише мітка інструмента)
• streaming.progress.commentary (за замовчуванням: false) вмикає текст коментарів і вступу асистента в тимчасовій чернетці перебігу роботи
• застарілі channels.telegram.streamMode, логічні значення streaming і вилучені ключі нативного попереднього перегляду чернетки виявляються; виконайте openclaw doctor --fix, щоб перенести їх

Рядки перебігу роботи інструментів — це короткі оновлення стану, які відображаються під час роботи інструментів (виконання команд, читання файлів, оновлення планування, підсумки виправлень, вступи й коментарі Codex у режимі сервера застосунку). У Telegram вони за замовчуванням увімкнені (відповідає поведінці випусків починаючи з v2026.4.22+).

Зберегти редагування попереднього перегляду відповіді, але приховати рядки перебігу роботи інструментів:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

Зберегти видимим перебіг роботи інструментів, але приховати текст команд і виконання:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

Режим progress показує перебіг роботи інструментів без редагування остаточної відповіді в цьому повідомленні. Розмістіть політику тексту команд у streaming.progress:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" вимикає редагування попереднього перегляду та пригнічує загальні повідомлення про роботу інструментів і перебіг процесу замість надсилання їх як окремих повідомлень стану; запити на схвалення, медіа та помилки й надалі передаються через звичайне остаточне доставлення. streaming.preview.toolProgress: false зберігає лише редагування попереднього перегляду відповіді.

Для лише текстових відповідей: короткі попередні перегляди остаточно редагуються на місці; для довгих остаточних відповідей, які розділяються на кілька повідомлень, попередній перегляд повторно використовується як перша частина, після чого надсилається лише решта; остаточні відповіді в режимі перебігу роботи очищають чернетку стану й використовують звичайне остаточне доставлення; якщо остаточне редагування завершується помилкою до підтвердження завершення, OpenClaw переходить до звичайного остаточного доставлення та очищає застарілий попередній перегляд. Для складних відповідей (корисних навантажень із медіа) OpenClaw завжди переходить до звичайного остаточного доставлення та очищає попередній перегляд.

Потоковий попередній перегляд і блокове потокове передавання взаємовиключні — коли блокове потокове передавання явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.

Міркування: /reasoning stream передає міркування в попередній перегляд наживо під час генерування, а потім видаляє попередній перегляд міркувань після остаточного доставлення (використовуйте /reasoning on, щоб залишити його видимим). Остаточна відповідь надсилається без тексту міркувань.

За замовчуванням вихідний текст використовує стандартні HTML-повідомлення Telegram, читабельні в актуальних клієнтах: напівжирний текст, курсив, посилання, код, спойлери, цитати — без розширених блоків, доступних лише в Bot API 10.2 (нативних таблиць, подробиць, розширених медіа, формул).

Увімкнення розширених повідомлень Bot API 10.2:

{channels: {telegram: {  richMessages: true,},},}

Коли ввімкнено: агент отримує інформацію, що для цього бота або облікового запису доступні розширені повідомлення (з підтримуваним контрактом створення Markdown та HTML-острівців); текст Markdown відтворюється через Markdown IR OpenClaw як типізовані розширені блоки Bot API 10.2 (заголовки, таблиці, подробиці, контрольні списки, розширені медіа, формули, мапи, колажі); підписи до медіа й надалі використовують HTML-підписи Telegram (розширені повідомлення не замінюють підписи, а довжина підпису обмежена 1024 символами).

Завдяки цьому текст моделі не містить сигілів розширеного Markdown Telegram, тому позначення валют на кшталт $400-600K не розбираються як математичні вирази. Довгий розширений текст автоматично розділяється відповідно до обмежень Telegram. Таблиці, що перевищують обмеження у 20 стовпців, замінюються блоком коду.

За замовчуванням: вимкнено задля сумісності з клієнтами — деякі актуальні клієнти для комп’ютерів, вебу, Android і сторонні клієнти відображають прийняті розширені повідомлення як непідтримувані. Не вмикайте цю функцію, якщо не всі клієнти, що використовуються з ботом, можуть їх відтворювати. /status показує, чи ввімкнено розширені повідомлення в поточному сеансі.

Попередні перегляди посилань увімкнено за замовчуванням. channels.telegram.linkPreview: false вимикає автоматичне виявлення сутностей у розширеному тексті.

Меню команд Telegram реєструється під час запуску за допомогою setMyCommands. commands.native: "auto" вмикає нативні команди для Telegram.

Додавання власних пунктів меню команд:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Резервне копіювання Git" },    { command: "generate", description: "Створити зображення" },  ],},},}

Правила: назви нормалізуються (початковий / видаляється, літери переводяться в нижній регістр); допустимий шаблон a-z, 0-9, _, довжина 1-32; власні команди не можуть перевизначати нативні; конфлікти й дублікати пропускаються та записуються в журнал.

Власні команди є лише пунктами меню — вони не реалізують поведінку автоматично. Команди Plugin/Skills можуть і далі працювати після введення, навіть якщо їх немає в меню Telegram. Якщо нативні команди вимкнено, вбудовані команди видаляються; власні команди й команди Plugin можуть усе одно реєструватися, якщо їх налаштовано.

Поширені помилки налаштування:

• setMyCommands failed з BOT_COMMANDS_TOO_MUCH після повторної спроби зі скороченням означає, що меню все ще переповнене; зменште кількість команд Plugin/Skills/власних команд або вимкніть channels.telegram.commands.native.
• Якщо deleteWebhook, deleteMyCommands або setMyCommands завершується помилкою 404: Not Found, тоді як прямі команди curl Bot API працюють, це зазвичай означає, що для channels.telegram.apiRoot указано повну кінцеву точку /bot<TOKEN>. apiRoot має містити лише кореневу адресу Bot API; openclaw doctor --fix видаляє випадковий кінцевий /bot<TOKEN>.
• getMe returned 401 означає, що Telegram відхилив налаштований токен бота. Оновіть botToken, tokenFile або TELEGRAM_BOT_TOKEN (обліковий запис за замовчуванням), указавши поточний токен BotFather; OpenClaw зупиняється до початку опитування, тому це не повідомляється як помилка очищення Webhook.
• setMyCommands failed з помилками мережі або отримання даних зазвичай означає, що вихідний доступ DNS/HTTPS до api.telegram.org заблоковано.

Команди сполучення пристроїв (Plugin device-pair)

Після встановлення:

1. /pair створює код налаштування
2. вставте код у застосунку iOS
3. /pair pending показує список запитів, що очікують на розгляд (зокрема роль і області доступу)
4. схвалення: /pair approve <requestId>, /pair approve (єдиний запит, що очікує на розгляд) або /pair approve latest

Якщо пристрій повторює спробу зі зміненими даними автентифікації (роллю, областями доступу, відкритим ключем), попередній запит, що очікує на розгляд, замінюється новим requestId; перед схваленням повторно виконайте /pair pending.

Докладніше: Сполучення.

Налаштування області дії вбудованої клавіатури:

{channels: {telegram: {  capabilities: {    inlineButtons: "allowlist",  },},},}

Перевизначення для окремого облікового запису:

{channels: {telegram: {  accounts: {    main: {      capabilities: {        inlineButtons: "allowlist",      },    },  },},},}

Області дії: off, dm, group, all, allowlist (за замовчуванням). Застарілий capabilities: ["inlineButtons"] зіставляється з "all".

Приклад дії з повідомленням:

{action: "send",channel: "telegram",to: "123456789",message: "Виберіть варіант:",buttons: [[  { text: "Так", callback_data: "yes" },  { text: "Ні", callback_data: "no" },],[{ text: "Скасувати", callback_data: "cancel" }],],}

Приклад кнопки Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "Відкрити застосунок:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Запустити", web_app: { url: "https://example.com/app" } }],  },],},}

Кнопки web_app працюють лише в приватних чатах між користувачем і ботом.

Клацання зворотних викликів, які не обробив зареєстрований інтерактивний обробник плагіна, передаються агенту як текст: callback_data: <value>.

Дії:

• 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, deleteMessage, reactions, sticker (типово: вимкнено). edit, createForumTopic і editForumTopic типово ввімкнені без окремого перемикача. Під час виконання для надсилання використовується активний знімок конфігурації та секретів із моменту запуску або перезавантаження, тому шляхи дій не визначають значення SecretRef повторно для кожного надсилання.

Семантика видалення реакцій: /tools/reactions.

Явні теги гілок відповідей у згенерованому виводі:

• [[reply_to_current]] — відповідь на повідомлення, яке спричинило дію
• [[reply_to:<id>]] — відповідь на повідомлення з певним ідентифікатором

channels.telegram.replyToMode: off (типово), first, all.

Коли гілки відповідей увімкнено й доступний початковий текст або підпис, OpenClaw автоматично додає вбудований фрагмент цитати. Telegram обмежує текст вбудованої цитати до 1024 кодових одиниць UTF-16; довші повідомлення цитуються від початку, а якщо Telegram відхиляє цитату, використовується звичайна відповідь.

off вимикає лише неявні гілки відповідей; явні теги [[reply_to_*]] і надалі враховуються.

Супергрупи-форуми: до ключів сеансів тем додається :topic:<threadId>; відповіді й індикатор набору тексту спрямовуються до гілки теми; шлях конфігурації теми — channels.telegram.groups.<chatId>.topics.<threadId>.

Загальна тема (threadId=1) є особливим випадком: під час надсилання повідомлень message_thread_id не вказується (Telegram відхиляє sendMessage(...thread_id=1) з повідомленням "гілку не знайдено"), але дії набору тексту все одно містять message_thread_id (емпірично це необхідно для появи індикатора набору тексту).

Записи тем успадковують налаштування групи, якщо їх не перевизначено (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId застосовується лише до теми й не успадковується з типових налаштувань групи. topics."*" задає типові значення для кожної теми в цій групі; точні ідентифікатори тем усе одно мають перевагу над "*".

Маршрутизація агента для кожної теми: кожну тему можна спрямувати до іншого агента через agentId у конфігурації теми, надавши їй власний робочий простір, пам’ять і сеанс:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Загальна тема -> головний агент            "3": { agentId: "zu" },        // Тема розробки -> агент zu            "5": { agentId: "coder" }      // Перевірка коду -> агент coder          }        }      }    }  }}

Після цього кожна тема має власний ключ сеансу, наприклад agent:zu:telegram:group:-1001234567890:topic:3.

Постійне прив’язування теми ACP: теми форуму можуть закріплювати сеанси середовища ACP за допомогою типізованих прив’язок верхнього рівня (bindings[] з type: "acp", match.channel: "telegram", peer.kind: "group" та ідентифікатором із кваліфікатором теми, наприклад -1001234567890:topic:42). Наразі область дії обмежена темами форумів у групах і супергрупах. Див. Агенти ACP.

Запуск ACP із чату з прив’язуванням до гілки: /acp spawn <agent> --thread here|auto прив’язує поточну тему до нового сеансу ACP; подальші повідомлення спрямовуються безпосередньо туди, а OpenClaw закріплює підтвердження запуску в темі. Потрібен channels.telegram.threadBindings.spawnSessions (типово: true).

Контекст шаблону надає MessageThreadId і IsForum. Особисті чати з message_thread_id зберігають метадані відповіді, але використовують ключі сеансів з урахуванням гілок лише тоді, коли Telegram getMe повідомляє has_topics_enabled: true. Застарілі перевизначення dm.threadReplies і direct.*.threadReplies видалено; режим гілок BotFather є єдиним джерелом істини. Виконайте openclaw doctor --fix, щоб видалити застарілі ключі конфігурації.

Аудіоповідомлення

Telegram розрізняє голосові повідомлення й аудіофайли. Типово використовується поведінка аудіофайлу; додайте тег [[audio_as_voice]] у відповідь агента, щоб примусово надіслати голосове повідомлення. Транскрипції вхідних голосових повідомлень у контексті агента позначаються як машинно згенерований ненадійний текст, але для виявлення згадок і надалі використовується необроблена транскрипція, тому голосові повідомлення з обов’язковою згадкою продовжують працювати.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

Відеоповідомлення

Telegram розрізняє відеофайли й відеоповідомлення. Відеоповідомлення не підтримують підписи; наданий текст повідомлення надсилається окремо.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

Місця та заклади

Використовуйте наявну дію send з одним окремим об’єктом location. Координати надсилають вбудовану позначку; додавання одночасно name і address надсилає вбудовану картку закладу. Надсилання місця не можна поєднувати з текстом повідомлення або медіафайлом.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Ейфелева вежа",address: "Марсове поле, Париж",},}

Наліпки

Вхідні дані: статичний WEBP завантажується й обробляється (заповнювач <media:sticker>); анімовані TGS і відео WEBM пропускаються.

Поля контексту наліпки: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Описи кешуються у стані плагіна OpenClaw у SQLite, щоб зменшити кількість повторних викликів розпізнавання зображень.

Увімкнення дій із наліпками:

{channels: {telegram: {  actions: {    sticker: true,  },},},}

Надсилання:

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

Пошук кешованих наліпок:

{action: "sticker-search",channel: "telegram",query: "кіт махає лапою",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 для опитування/Webhook автоматично містять message_reaction.

ackReaction надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення. messages.ackReactionScope визначає, коли його буде надіслано.

Порядок визначення емодзі:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• резервний емодзі ідентичності агента (agents.list[].identity.emoji, інакше "👀")

Telegram очікує емодзі Unicode (наприклад, "👀"); використовуйте "", щоб вимкнути реакцію для каналу або облікового запису.

Область дії (messages.ackReactionScope, типово "group-mentions"; наразі без перевизначення для облікового запису або каналу Telegram):

all (особисті чати + групи, включно з фоновими подіями кімнати), direct (лише особисті чати), group-all (кожне групове повідомлення, крім фонових подій кімнати, без особистих чатів), group-mentions (групи, коли згадано бота; без особистих чатів — типове значення), off / none (вимкнено).

Запис конфігурації каналу типово ввімкнено (configWrites !== false). Записи, ініційовані Telegram, включають події міграції груп (migrate_to_chat_id, оновлює channels.telegram.groups) і /config set / /config unset (потрібно ввімкнути команди).

Вимкнення:

{channels: {telegram: {  configWrites: false,},},}

Типово використовується тривале опитування. Для режиму Webhook задайте channels.telegram.webhookUrl і channels.telegram.webhookSecret; необов’язково webhookPath (типово /telegram-webhook), webhookHost (типово 127.0.0.1), webhookPort (типово 8787), webhookCertPath (PEM самопідписаного сертифіката для конфігурацій із прямою IP-адресою або без домену).

У режимі тривалого опитування OpenClaw зберігає позначку перезапуску лише після успішної диспетчеризації оновлення; якщо обробник завершується помилкою, оновлення можна повторити в тому самому процесі, а не позначати завершеним.

Локальний слухач типово прив’язується до 127.0.0.1:8787. Для публічного вхідного трафіку розмістіть зворотний проксі перед локальним портом або навмисно задайте webhookHost: "0.0.0.0".

Режим Webhook перевіряє захист запиту, секретний токен Telegram і тіло JSON, а потім фіксує оновлення у своїй стійкій черзі вхідних даних, перш ніж повернути порожню відповідь 200. Успішне стійке прийняття містить x-openclaw-delivery-accepted: durable; відповіді перевірки справності, маршрутизації, автентифікації, валідації та помилок сховища не містять цього заголовка. Зворотні проксі й контролери хостів можуть вимагати цей заголовок, щоб відрізняти прийняття OpenClaw від загальної порожньої відповіді 200, не визначаючи прийняття за часом відповіді.

Потім OpenClaw асинхронно обробляє оновлення через ті самі смуги бота для кожного чату й кожної теми, що використовуються для тривалого опитування, тому повільні цикли агента не затримують підтвердження доставки Telegram.

• channels.telegram.textChunkLimit за замовчуванням має значення 4000; streaming.chunkMode="newline" надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
• channels.telegram.mediaMaxMb (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів.
• channels.telegram.mediaGroupFlushMs (за замовчуванням 500, діапазон 10-60000) визначає, як довго альбоми/групи медіафайлів буферизуються, перш ніж OpenClaw передасть їх як одне вхідне повідомлення. Збільште значення, якщо частини альбому надходять із запізненням; зменште його, щоб скоротити затримку відповіді на альбом.
• channels.telegram.timeoutSeconds перевизначає час очікування клієнта 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 імпортує застарілі бічні файли. Telegram додає лише один неглибокий reply_to_message до кожного оновлення, тому ланцюжки, старші за кеш, обмежені цим корисним навантаженням.
• списки дозволених користувачів Telegram передусім визначають, хто може запускати агента, а не слугують повною межею редагування додаткового контексту.
• історія приватних повідомлень: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Для доставлення остаточної вхідної відповіді використовується обмежена безпечна повторна спроба в разі помилок до встановлення з’єднання, але повторні спроби не виконуються для неоднозначних мережевих конвертів після надсилання, які можуть дублювати видимі повідомлення.

Цілі надсилання CLI та інструмента повідомлень приймають числовий ідентифікатор чату, ім’я користувача або ціль теми форуму:

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"

Опитування використовують openclaw message poll і підтримують теми форуму:

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:). --poll-option повторюється 2-12 разів (обмеження Telegram на кількість варіантів).

Надсилання Telegram також підтримує --presentation із блоками buttons для вбудованих клавіатур (якщо це дозволяє channels.telegram.capabilities.inlineButtons), --pin або --delivery '{"pin":true}' для запиту закріпленого доставлення, коли бот може закріплювати повідомлення в цьому чаті, а також --force-document для надсилання вихідних зображень, GIF-файлів і відео як документів замість стиснених зображень, анімацій або відео.

Керування доступністю дій: channels.telegram.actions.sendMessage=false вимикає всі вихідні повідомлення, зокрема опитування; channels.telegram.actions.poll=false вимикає створення опитувань, залишаючи звичайне надсилання ввімкненим.

Telegram підтримує схвалення виконання у приватних повідомленнях осіб, які схвалюють, і за бажанням може публікувати запити у вихідному чаті або темі. Особи, які схвалюють, мають бути вказані числовими ідентифікаторами користувачів Telegram.

• channels.telegram.execApprovals.enabled ("auto" вмикає функцію, якщо можна визначити принаймні одну особу, яка схвалює)
• channels.telegram.execApprovals.approvers (резервно використовує числові ідентифікатори власників із commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (за замовчуванням) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom і defaultTo визначають, хто може спілкуватися з ботом і куди він надсилає звичайні відповіді — вони не надають нікому права схвалювати виконання. Перше схвалене сполучення через приватні повідомлення ініціалізує commands.ownerAllowFrom, якщо власника команд ще немає, тому конфігурації з одним власником працюють без дублювання ідентифікаторів у execApprovals.approvers.

Під час доставлення в канал текст команди відображається в чаті; вмикайте channel або both лише в довірених групах/темах. Коли запит надходить у тему форуму, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. За замовчуванням строк дії схвалень виконання завершується через 30 хвилин.

Вбудовані кнопки схвалення також потребують, щоб channels.telegram.capabilities.inlineButtons дозволяв цільову поверхню (dm, group або all). Ідентифікатори схвалення з префіксом plugin: визначаються через схвалення Plugin; решта спочатку визначається через схвалення виконання.

Див. Схвалення виконання.

• Якщо requireMention=false, режим приватності Telegram має дозволяти повну видимість: BotFather /setprivacy -> Disable, потім видаліть бота з групи й додайте його знову.
• openclaw channels status попереджає, коли конфігурація передбачає групові повідомлення без згадки.
• openclaw channels status --probe перевіряє явні числові ідентифікатори груп; належність до групи за шаблоном "*" перевірити неможливо.
• Швидка перевірка сеансу: /activation always.

• Якщо існує channels.telegram.groups, група має бути вказана в списку (або список має містити "*").
• Перевірте членство бота в групі.
• Перегляньте openclaw logs --follow, щоб дізнатися причини пропуску.

• Авторизуйте особу відправника (сполучення та/або числовий allowFrom); авторизація команд застосовується, навіть якщо політика групи має значення open.
• setMyCommands failed з BOT_COMMANDS_TOO_MUCH означає, що нативне меню містить забагато пунктів; скоротіть кількість команд Plugin/Skills/власних команд або вимкніть нативні меню.
• Виклики запуску deleteMyCommands / setMyCommands і виклики індикації набору sendChatAction обмежені в часі та в разі завершення часу очікування запиту повторюються один раз через резервний транспорт Telegram. Постійні помилки мережі/отримання зазвичай означають, що DNS/HTTPS-з’єднання з api.telegram.org недоступне.

• getMe returned 401 — це помилка автентифікації Telegram для налаштованого токена бота. Знову скопіюйте або згенеруйте токен у BotFather, а потім оновіть channels.telegram.botToken, tokenFile, accounts.<id>.botToken або TELEGRAM_BOT_TOKEN (обліковий запис за замовчуванням).
• deleteWebhook 401 Unauthorized під час запуску також є помилкою автентифікації; трактування її як «Webhook не існує» лише відкладе ту саму помилку неправильного токена до наступного виклику API.

• Node 22+ із власним fetch/проксі може спричинити негайне переривання, якщо типи AbortSignal не збігаються.
• Деякі хости спочатку визначають для api.telegram.org адресу IPv6; несправний вихідний IPv6-зв’язок спричиняє періодичні збої API.
• Записи журналу з TypeError: fetch failed або Network request for 'getUpdates' failed! повторюються як відновлювані мережеві помилки.
• Під час запуску опитування OpenClaw повторно використовує успішну початкову перевірку getMe для grammY, тому засобу виконання не потрібен другий getMe перед першим getUpdates.
• Якщо deleteWebhook завершується транзитною мережевою помилкою під час запуску опитування, OpenClaw переходить до тривалого опитування замість ще одного виклику площини керування перед опитуванням. Якщо Webhook усе ще активний, це проявляється як конфлікт getUpdates; OpenClaw перебудовує транспорт і повторює очищення Webhook.
• Якщо сокети Telegram повторно створюються через короткі фіксовані проміжки часу, перевірте, чи не задано низьке значення channels.telegram.timeoutSeconds — клієнти ботів обмежують налаштовані значення, нижчі за захисні інтервали вихідних запитів і запитів getUpdates, але старіші випуски могли переривати кожне опитування або відповідь, якщо значення було нижчим за ці інтервали.
• Polling stall detected у журналах означає, що OpenClaw перезапускає опитування та перебудовує транспорт після 120 секунд без завершеного підтвердження працездатності тривалого опитування за замовчуванням.
• openclaw channels status --probe і openclaw doctor попереджають, коли активний обліковий запис опитування не завершив getUpdates після пільгового періоду запуску, активний обліковий запис Webhook не завершив setWebhook після пільгового періоду запуску або остання успішна активність транспорту опитування застаріла.
• Збільшуйте channels.telegram.pollingStallThresholdMs лише тоді, коли тривалі виклики getUpdates працюють справно, але хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай указують на проблеми проксі, DNS, IPv6 або вихідного TLS-з’єднання з api.telegram.org.
• Telegram враховує змінні середовища проксі процесу для транспорту Bot API: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY і варіанти в нижньому регістрі. NO_PROXY / no_proxy усе ще можуть обходити api.telegram.org.
• Якщо для середовища служби задано OPENCLAW_PROXY_URL, а стандартних змінних середовища проксі немає, Telegram також використовує цю URL-адресу для транспорту Bot API.
• На VPS-хостах із нестабільним прямим вихідним з’єднанням/TLS спрямовуйте виклики API Telegram через проксі:

channels:telegram:proxy: socks5://<user>:<password>@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, примусово задайте вибір сімейства:

channels:telegram:network:  autoSelectFamily: false

• Відповіді з діапазону еталонного тестування RFC 2544 (198.18.0.0/15) уже за замовчуванням дозволені для завантаження медіафайлів Telegram. Якщо довірений проксі із підробленими IP-адресами або прозорий проксі під час завантаження медіафайлів перетворює api.telegram.org на іншу приватну, внутрішню адресу чи адресу спеціального призначення, увімкніть обхід лише для Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• Таке саме явне ввімкнення доступне для кожного облікового запису в channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Якщо ваш проксі перетворює адреси хостів медіафайлів Telegram на 198.18.x.x, спочатку не вмикайте небезпечний прапорець — цей діапазон уже дозволено за замовчуванням.

• Тимчасові перевизначення через змінні середовища: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Перевірте відповіді DNS:

dig +short api.telegram.org Adig +short api.telegram.org AAAA