Telegram

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

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

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

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

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

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

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

OpenClaw може транслювати часткові відповіді в реальному часі:

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

Оновлення попереднього перегляду перебігу інструментів — це короткі рядки статусу, які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram стандартно лишає їх увімкненими, щоб відповідати випущеній поведінці OpenClaw з v2026.4.22 і новіших версій. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки перебігу інструментів, задайте:

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

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

{
  "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 пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.

Потік міркувань лише для Telegram:

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

Вихідний текст використовує Telegram parse_mode: "HTML".

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

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

Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо це налаштовано.

Поширені помилки налаштування:

• 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 було встановлено на повний endpoint /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 заблоковано.

# Команди спарювання пристрою (plugin device-pair)

Коли plugin device-pair установлено:

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

Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap утримує токен primary node на scopes: []; будь-який переданий operator-токен залишається обмеженим до operator.approvals, operator.read, operator.talk.secrets і operator.write. Перевірки областей доступу bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише operator-запити; ролі, що не є операторами, усе ще потребують областей доступу під власним префіксом ролі.

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

Докладніше: Спарювання.

Налаштуйте область inline keyboard:

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

Натискання callback передаються агенту як текст: callback_data: <value>

Дії інструментів Telegram включають:

• sendMessage (to, content, необов’язково mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, необов’язково iconColor, iconCustomEmojiId)

Дії повідомлень каналу надають ергономічні псевдоніми (send, react, delete, edit, sticker, sticker-search, topic-create).

Елементи керування gating:

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

Примітка: edit і topic-create наразі ввімкнено за замовчуванням, і вони не мають окремих перемикачів channels.telegram.actions.*. Runtime-надсилання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання 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 застосовується лише до теми й не успадковується зі стандартних параметрів групи.

Маршрутизація агентів за темами: Кожна тема може маршрутизуватися до іншого агента шляхом встановлення 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" та topic-qualified id на кшталт -1001234567890:topic:42). Наразі обмежено темами форуму в групах/супергрупах. Див. Агенти ACP.

Thread-bound ACP spawn із чату: /acp spawn <agent> --thread here|auto прив’язує поточну тему до нової сесії ACP; наступні повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження spawn у темі. Потрібно, щоб channels.telegram.threadBindings.spawnSessions залишалося ввімкненим (за замовчуванням: true).

Контекст шаблону надає MessageThreadId і IsForum. DM-чати з message_thread_id типово зберігають маршрутизацію DM та метадані відповідей у пласких сесіях; вони використовують ключі сесій з урахуванням гілок лише тоді, коли налаштовано threadReplies: "inbound", threadReplies: "always", requireTopic: true або відповідну конфігурацію теми. Використовуйте верхньорівневий channels.telegram.dm.threadReplies як стандарт для облікового запису або direct.<chatId>.threadReplies для одного DM.

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

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

Файл кешу стікерів:

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

allowed_updates для polling/Webhook автоматично включає message_reaction.

ackReaction надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.

Порядок визначення:

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

Примітки:

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

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

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

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

Вимкнути:

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

Типово використовується довге 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. Для публічного входу або поставте зворотний проксі перед локальним портом, або свідомо задайте webhookHost: "0.0.0.0".

Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло перед поверненням 200 до Telegram. Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/теми, що й у 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 перевизначає timeout клієнта Telegram API (якщо не задано, застосовується стандарт grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисту вихідного запиту тексту/набору тексту, щоб grammY не переривав доставку видимої відповіді до того, як зможуть спрацювати транспортний захист OpenClaw і fallback. Long polling усе одно використовує 45-секундний захист запиту getUpdates, щоб не залишати неактивні polls покинутими безстроково.
• channels.telegram.pollingStallThresholdMs типово дорівнює 120000; налаштовуйте в межах від 30000 до 600000 лише для хибнопозитивних перезапусків через stall polling.
• історія контексту групи використовує channels.telegram.historyLimit або messages.groupChat.historyLimit (типово 50); 0 вимикає.
• додатковий контекст відповіді/цитати/пересилання наразі передається в отриманому вигляді.
• allowlists Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
• Елементи керування історією DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• конфігурація channels.telegram.retry застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення.

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

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 polls використовують 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

Прапорці poll лише для 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 як документи замість стислих фото або завантажень animated-media

Обмеження дій:

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

Telegram підтримує схвалення exec у DM затверджувачів і може додатково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.

Шлях конфігурації:

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

channels.telegram.allowFrom, groupAllowFrom і defaultTo керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось затверджувачем exec. Перша схвалена пара DM bootstrap-ить 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/Skills/власних команд або вимкніть нативні меню
• стартові виклики 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/проксі можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
• Деякі хости спочатку розв’язують api.telegram.org в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API.
• Якщо журнали містять TypeError: fetch failed або Network request for 'getUpdates' failed!, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки.
• Під час запуску polling OpenClaw повторно використовує успішну стартову перевірку getMe для grammY, тож runner не потребує другого getMe перед першим getUpdates.
• Якщо deleteWebhook завершується тимчасовою мережевою помилкою під час запуску polling, OpenClaw переходить до long polling замість виконання ще одного перед-polling виклику control plane. Webhook, що все ще активний, проявляється як конфлікт getUpdates; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення webhook.
• Якщо сокети Telegram перезапускаються з коротким фіксованим інтервалом, перевірте, чи не занизьке channels.telegram.timeoutSeconds; клієнти ботів обмежують налаштовані значення нижче захисних меж вихідних запитів і getUpdates, але старіші випуски могли переривати кожен poll або відповідь, коли це значення було нижче за ці межі.
• Якщо журнали містять Polling stall detected, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
• openclaw channels status --probe і openclaw doctor попереджають, коли запущений обліковий запис polling не завершив getUpdates після стартового пільгового періоду, коли запущений обліковий запис webhook не завершив setWebhook після стартового пільгового періоду або коли остання успішна активність транспорту polling застаріла.
• Збільшуйте channels.telegram.pollingStallThresholdMs лише тоді, коли довготривалі виклики getUpdates справні, але ваш хост усе одно повідомляє про хибні перезапуски через polling-stall. Постійні зависання зазвичай указують на проблеми проксі, DNS, IPv6 або вихідного TLS між хостом і api.telegram.org.
• Telegram також враховує змінні середовища проксі процесу для транспорту Bot API, зокрема HTTP_PROXY, HTTPS_PROXY, ALL_PROXY та їхні варіанти в нижньому регістрі. NO_PROXY / no_proxy усе ще можуть обходити api.telegram.org.
• Якщо керований проксі OpenClaw налаштовано через OPENCLAW_PROXY_URL для сервісного середовища, а стандартних змінних середовища проксі немає, 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

• Відповіді діапазону benchmark 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 уже дозволяє діапазон 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