Telegram

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

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

• 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, щоб перенести їх

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

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

• 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

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

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

​

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

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

​

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

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

​

Наліпки

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "кіт махає лапою",
  limit: 5,
}

• channels.telegram.reactionNotifications: off | own | all (типово: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (типово: minimal)

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

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

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

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

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