Telegram

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

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

• direct chats: повідомлення попереднього перегляду + editMessageText
• групи/topics: повідомлення попереднього перегляду + editMessageText

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

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

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

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

• Markdown-подібний текст рендериться в безпечний для Telegram HTML.
• Підтримувані HTML-теги Telegram зберігаються; непідтримуваний HTML екранується.
• Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст.

• 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/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram

• setMyCommands failed з BOT_COMMANDS_TOO_MUCH означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд plugin/skill/користувацьких команд або вимкніть 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 зупиняється до polling, тому це не повідомляється як помилка очищення 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" }],
  ],
}

• sendMessage (to, content, необов’язково mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• 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

• ~/.openclaw/telegram/sticker-cache.json

{
  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 спостерігав батьківські повідомлення; кеш спостережених повідомлень зберігається поруч зі сховищем сесій. Telegram включає в оновлення лише один поверхневий reply_to_message, тому ланцюжки, старші за кеш, обмежені поточним корисним навантаженням оновлення Telegram.
• allowlist 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 переходить до long polling замість ще одного передопитувального виклику control-plane. Активний webhook проявляється як конфлікт getUpdates; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення webhook.
• Якщо сокети Telegram повторно створюються з коротким фіксованим інтервалом, перевірте, чи не занизьке channels.telegram.timeoutSeconds; клієнти ботів обмежують налаштовані значення нижче outbound-запобіжників і запобіжників запитів getUpdates, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці запобіжники.
• Якщо журнали містять Polling stall detected, OpenClaw перезапускає опитування і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки живучості long-poll за замовчуванням.
• 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, примусово задайте вибір family:

channels:
  telegram:
    network:
      autoSelectFamily: false

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

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Те саме явне ввімкнення доступне для кожного облікового запису за адресою channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Якщо ваш proxy розв’язує медіахости Telegram у 198.18.x.x, спершу залиште небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон 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