Telegram

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

Якщо бот має бачити всі групові повідомлення, виконайте одне з такого:

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

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

Статус адміністратора контролюється в налаштуваннях групи Telegram.

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

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

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 і пізніших версій.

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

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

Щоб залишити прогрес інструментів видимим, але приховати текст команд/exec, задайте:

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

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

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

Використовуйте streaming.mode: "off" лише коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальний шум інструментів/прогресу приглушується замість надсилання окремими статусними повідомленнями. Запити на схвалення, медіа-навантаження та помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте 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:

{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

Додайте користувацькі записи меню команд:

{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<TOKEN>. apiRoot має бути лише коренем Bot API, а openclaw doctor --fix видаляє випадковий кінцевий /bot<TOKEN>.
• 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 <requestId> для явного схвалення
   • /pair approve, коли є лише один очікуваний запит
   • /pair approve latest для найновішого

Код налаштування містить короткоживучий bootstrap-токен. Вбудований bootstrap коду налаштування повертає довготривалий токен вузла з scopes: [] плюс обмежений токен передавання оператору для довіреного мобільного onboarding. Цей токен оператора може читати власну конфігурацію часу налаштування, але не надає областей дії мутації сполучення або operator.admin.

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

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

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

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

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

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

Області дії:

• off
• dm
• group
• all
• allowlist (за замовчуванням)

Застаріле capabilities: ["inlineButtons"] зіставляється з inlineButtons: "all".

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

{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:

{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: <value>

Дії інструментів 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

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

• [[reply_to_current]] відповідає на повідомлення, що ініціювало дію
• [[reply_to:<id>]] відповідає на конкретний ID повідомлення Telegram

channels.telegram.replyToMode керує обробкою:

• off (за замовчуванням)
• first
• all

Коли гілкування відповідей увімкнене й доступний оригінальний текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. 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."*" задає типові налаштування для кожної теми в цій групі; точні ID тем усе одно мають пріоритет над "*".

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

{  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.

Запуск ACP із чату з прив’язкою до гілки: /acp spawn <agent> --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]] у відповіді агента, щоб примусово надіслати голосову нотатку
• транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий транскрипт, тому голосові повідомлення, обмежені згадками, продовжують працювати.

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

{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,}

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

Стікери

Обробка вхідних стікерів:

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

Поля контексту стікера:

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

Описи стікерів кешуються у стані Plugin OpenClaw SQLite, щоб зменшити кількість повторних викликів зору.

Увімкнути дії зі стікерами:

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

Дія надсилання стікера:

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

Пошук кешованих стікерів:

{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.<accountId>.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" (вимкнено).

Записи конфігурації каналу ввімкнені типово (configWrites !== false).

Записи, ініційовані Telegram, включають:

• події міграції групи (migrate_to_chat_id) для оновлення channels.telegram.groups
• /config set і /config unset (потребує ввімкнення команд)

Вимкнути:

{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["<user_id>"].historyLimit
• конфігурація channels.telegram.retry застосовується до помічників надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставлення фінальної відповіді для вхідних повідомлень також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві обгортки після надсилання, які можуть дублювати видимі повідомлення.

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

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 і підтримують теми форуму:

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.

• Якщо 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.<id>.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:

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 за замовчуванням. Якщо довірений fake-IP або прозорий проксі переписує api.telegram.org на якусь іншу приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете увімкнути обхід лише для Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

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

• Перевизначення середовища (тимчасові):
  • 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