Telegram

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

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

• прямі чати: повідомлення попереднього перегляду + 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

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

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

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

• короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці
• довгі фінальні тексти, які розбиваються на кілька повідомлень Telegram, за можливості повторно використовують наявний попередній перегляд як перший фінальний фрагмент, а потім надсилають лише решту фрагментів
• фінальні відповіді в режимі progress очищають чернетковий статус і використовують звичайну фінальну доставку замість редагування чернетки у відповідь
• якщо фінальне редагування не вдається до підтвердження завершеного тексту, OpenClaw використовує звичайну фінальну доставку та очищає застарілий попередній перегляд

• /reasoning stream використовує шлях попереднього перегляду reasoning підтримуваного каналу; у Telegram він транслює reasoning у живий попередній перегляд під час генерації
• попередній перегляд reasoning видаляється після фінальної доставки; використовуйте /reasoning on, коли reasoning має залишатися видимим
• фінальна відповідь надсилається без тексту reasoning

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

• Агенту повідомляється, що розширені повідомлення Telegram доступні для цього бота/облікового запису.
• Текст Markdown рендериться через Markdown IR OpenClaw і надсилається як розширений HTML Telegram.
• Явні розширені HTML-навантаження зберігають підтримувані теги Bot API 10.1, як-от заголовки, таблиці, details, rich media та формули.
• Підписи до медіа все ще використовують HTML-підписи Telegram, бо розширені повідомлення не замінюють підписи.

• 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

• 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)

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

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

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

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

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, необов’язково mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content або caption, необов’язкові вбудовані кнопки presentation; редагування лише кнопок оновлює розмітку відповіді)
• createForumTopic (chatId, name, необов’язково iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (за замовчуванням: вимкнено)

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

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

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

• надсилання повідомлень пропускають message_thread_id (Telegram відхиляє sendMessage(...thread_id=1))
• дії індикатора набору все одно включають message_thread_id

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

​

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

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

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

​

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

{
  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

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

• 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), а не до точної початкової теми

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

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

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

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

• Стандартне значення 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 до підключення, але не повторює неоднозначні мережеві обгортки після надсилання, які можуть дублювати видимі повідомлення.

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id для тем форуму (або використовуйте ціль :topic:)

• --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, залишаючи звичайні надсилання ввімкненими

• channels.telegram.execApprovals.enabled (автоматично вмикається, коли можна розв’язати принаймні одного схвалювача)
• channels.telegram.execApprovals.approvers (відступає до числових ID власників із commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (стандартно) | channel | both
• agentFilter, sessionFilter

• Якщо 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 A
dig +short api.telegram.org AAAA