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

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

• прямі чати: повідомлення попереднього перегляду + editMessageText
• групи/теми: повідомлення попереднього перегляду + editMessageText

• channels.telegram.streaming має бути off | partial | block | progress (за замовчуванням: partial)
• progress у Telegram відображається як partial (сумісність із міжканальним найменуванням)
• streaming.preview.toolProgress керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: true). Установіть false, щоб зберігати окремі повідомлення інструментів/прогресу.
• застарілі channels.telegram.streamMode і булеві значення streaming автоматично відображаються

• DM: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)
• група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)

• /reasoning stream надсилає reasoning у live preview під час генерації
• фінальна відповідь надсилається без тексту reasoning

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

• commands.native: "auto" вмикає нативні команди для Telegram

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

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

• користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично
• команди Plugin/Skills можуть і далі працювати при ручному введенні, навіть якщо вони не показані в меню Telegram

• setMyCommands failed з BOT_COMMANDS_TOO_MUCH означає, що меню Telegram усе ще переповнене навіть після скорочення; зменште кількість користувацьких команд/команд Plugin/Skills або вимкніть channels.telegram.commands.native.
• setMyCommands failed з помилками network/fetch зазвичай означає, що вихідний DNS/HTTPS до api.telegram.org заблокований.

​

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

1. /pair генерує код налаштування
2. вставте код у застосунок iOS
3. /pair pending показує список запитів, що очікують на розгляд (включно з role/scopes)
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: "Виберіть варіант:",
  buttons: [
    [
      { text: "Так", callback_data: "yes" },
      { text: "Ні", callback_data: "no" },
    ],
    [{ text: "Скасувати", 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>
• відповіді й набір тексту націлюються на тред теми
• шлях config теми: 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" },      // Загальна тема → агент main
            "3": { agentId: "zu" },        // Тема розробки → агент zu
            "5": { agentId: "coder" }      // Рев’ю коду → агент coder
          }
        }
      }
    }
  }
}

• bindings[] з type: "acp" і match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto може прив’язати поточну тему Telegram до нової ACP-сесії.
• Наступні повідомлення в темі маршрутизуються безпосередньо до прив’язаної ACP-сесії (без потреби в /acp steer).
• Після успішної прив’язки OpenClaw закріплює повідомлення-підтвердження запуску в темі.
• Потрібно channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• приватні чати з message_thread_id зберігають DM-маршрутизацію, але використовують thread-aware ключі сесій/цілі відповідей.

​

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

• за замовчуванням: поведінка аудіофайлу
• тег [[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 означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
• Події реакцій усе одно дотримуються контролю доступу Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); неавторизовані відправники відкидаються.
• Telegram не надає ID тредів в оновленнях реакцій.
  • нефорумні групи маршрутизуються до сесії групового чату
  • форумні групи маршрутизуються до сесії загальної теми групи (:topic:1), а не до точної початкової теми

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

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

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

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

• задайте channels.telegram.webhookUrl
• задайте channels.telegram.webhookSecret (обов’язково, коли задано URL webhook)
• необов’язково channels.telegram.webhookPath (за замовчуванням /telegram-webhook)
• необов’язково channels.telegram.webhookHost (за замовчуванням 127.0.0.1)
• необов’язково channels.telegram.webhookPort (за замовчуванням 8787)

• channels.telegram.textChunkLimit за замовчуванням має значення 4000.
• channels.telegram.chunkMode="newline" надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
• channels.telegram.mediaMaxMb (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram.
• channels.telegram.timeoutSeconds перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується значення grammY за замовчуванням).
• channels.telegram.pollingStallThresholdMs за замовчуванням дорівнює 120000; налаштовуйте в межах 30000–600000 лише для хибнопозитивних перезапусків через зависання polling.
• історія контексту групи використовує channels.telegram.historyLimit або messages.groupChat.historyLimit (за замовчуванням 50); 0 вимикає її.
• додатковий контекст reply/quote/forward наразі передається як отримано.
• allowlist Telegram насамперед обмежують, хто може викликати агента, а не є повноцінною межею редагування додаткового контексту.
• елементи керування історією DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• config channels.telegram.retry застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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

• --buttons для вбудованих клавіатур, коли це дозволяє channels.telegram.capabilities.inlineButtons
• --force-document, щоб надсилати вихідні зображення та GIF як документи, а не як стиснені фото чи анімовані медіазавантаження

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

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (необов’язково; інакше використовуються числові ID власників, виведені з allowFrom і прямого defaultTo, де це можливо)
• channels.telegram.execApprovals.target (dm | channel | both, за замовчуванням: dm)
• agentFilter, sessionFilter

• target: "dm" надсилає запити на підтвердження лише в DM визначених затверджувачів
• target: "channel" надсилає запит назад у початковий чат/тему Telegram
• target: "both" надсилає і в DM затверджувачів, і в початковий чат/тему

• ID з префіксом plugin: завжди визначаються через підтвердження plugin.
• Інші ID спочатку пробують exec.approval.resolve.
• Якщо Telegram також авторизований для підтверджень plugin і gateway повідомляє, що підтвердження exec невідоме або сплило, Telegram один раз повторює спробу через plugin.approval.resolve.
• Реальні відмови/помилки підтвердження exec не переходять мовчки до визначення підтвердження plugin.

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

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

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

• Node 22+ + власний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
• Деякі хости спочатку визначають api.telegram.org в IPv6; несправний вихідний IPv6 може спричиняти переривчасті збої Telegram API.
• Якщо журнали містять TypeError: fetch failed або Network request for 'getUpdates' failed!, OpenClaw тепер повторює їх як відновлювані помилки мережі.
• Якщо журнали містять Polling stall detected, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки живості long-poll за замовчуванням.
• Збільшуйте channels.telegram.pollingStallThresholdMs лише тоді, коли довготривалі виклики getUpdates є здоровими, але ваш хост усе одно повідомляє про хибнопозитивні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або TLS egress між хостом і api.telegram.org.
• На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через channels.telegram.proxy:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ за замовчуванням використовує autoSelectFamily=true (крім WSL2) і dnsResultOrder=ipv4first.
• Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір family:

channels:
  telegram:
    network:
      autoSelectFamily: false

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

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

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

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