chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
7c2a4dbfaf
commit
8000c1caa3
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Статус підтримки бота Telegram, можливості та конфігурація
|
||||
summary: Стан підтримки бота Telegram, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T15:47:48Z"
|
||||
generated_at: "2026-05-03T15:57:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5f234bc5f33eacbed3bfdc9d60285ea22ce4747f727cdb13863732238470a62d
|
||||
source_hash: 730b26df661d5faacdc393b1a017ac36ee38371b9cee6a6dffe8b627566ce2e2
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово для продакшену для особистих повідомлень ботам і груп через grammY. Long polling є режимом за замовчуванням; режим webhook є необов’язковим.
|
||||
Готовий для production-використання в DM ботів і групах через grammY. Режим довгого опитування є стандартним; режим Webhook необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Політика особистих повідомлень за замовчуванням для Telegram — сполучення.
|
||||
Стандартна політика DM для Telegram — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами та інструкції з відновлення.
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
@ -30,13 +30,13 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
Відкрийте Telegram і напишіть **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Налаштуйте токен і політику особистих повідомлень">
|
||||
<Step title="Налаштуйте токен і політику DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть gateway і схваліть перше особисте повідомлення">
|
||||
<Step title="Запустіть gateway і схваліть перший DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -74,21 +74,21 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
<Accordion title="Режим приватності та видимість груп">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує групові повідомлення, які вони отримують.
|
||||
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з такого:
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з двох:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
Під час перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -110,35 +110,35 @@ openclaw pairing approve telegram <CODE>
|
||||
## Контроль доступу та активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика особистих повідомлень">
|
||||
`channels.telegram.dmPolicy` керує доступом до особистих повідомлень:
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потребує принаймні одного ID відправника в `allowFrom`)
|
||||
- `open` (потребує, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` із `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із суворо обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає username бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об’єднання все ще не містить явного wildcard.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється валідацією конфігурації.
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття все ще не містить явний wildcard.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися й ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токена бота Telegram).
|
||||
Якщо ви оновилися і ваш config містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (найкраща спроба; потребує токена бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення).
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була довговічною в config (замість залежності від попередніх схвалень сполучення).
|
||||
|
||||
Поширена плутанина: схвалення сполучення в особистих повідомленнях не означає "цей відправник авторизований усюди".
|
||||
Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все одно походить із явних allowlists у конфігурації.
|
||||
Якщо ви хочете "я авторизований один раз, і працюють як особисті повідомлення, так і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
Поширена плутанина: схвалення сполучення DM не означає «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все одно походить з явних config allowlist.
|
||||
Якщо ви хочете «мене авторизовано один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
1. Напишіть своєму боту в особисті повідомлення.
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
@ -152,8 +152,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlists">
|
||||
Два елементи керування застосовуються разом:
|
||||
<Tab title="Політика груп і allowlist">
|
||||
Два засоби керування застосовуються разом:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає config `groups`:
|
||||
@ -161,22 +161,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: діє як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Яким відправникам дозволено в групах** (`channels.telegram.groupPolicy`)
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень для особистих повідомлень.
|
||||
Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM.
|
||||
Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в fail-closed режимі `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
|
||||
Приклад: дозволити лише конкретним користувачам в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,11 +211,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram.
|
||||
|
||||
- Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг звертатися до бота.
|
||||
|
||||
</Warning>
|
||||
|
||||
@ -224,21 +224,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Tab title="Поведінка згадок">
|
||||
Групові відповіді за замовчуванням потребують згадки.
|
||||
|
||||
Згадка може походити з:
|
||||
Згадка може надходити з:
|
||||
|
||||
- нативної згадки `@botusername`, або
|
||||
- шаблонів згадок у:
|
||||
- шаблонів згадки в:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд на рівні сесії:
|
||||
Перемикачі команд рівня сесії:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
Вони оновлюють лише стан сесії. Використовуйте config для збереження.
|
||||
|
||||
Приклад сталої конфігурації:
|
||||
Приклад постійного config:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,7 +256,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- перешліть групове повідомлення до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перегляньте Bot API `getUpdates`
|
||||
- або перевірте Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та placeholders медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми залишалися ізольованими.
|
||||
- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням тримає особисті повідомлення в плоскій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій тем в особистих повідомленнях.
|
||||
- Long polling використовує grammY runner із послідовністю за чатами/потоками. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений усередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller.
|
||||
- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеного liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням тримає DM у пласкій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` або відповідний config теми, коли ви навмисно хочете ізоляцію сесій тем DM.
|
||||
- Довге опитування використовує runner grammY з послідовністю для кожного чату/потоку. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший OpenClaw gateway, script або зовнішній poller, імовірно, використовує той самий токен.
|
||||
- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через stall опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для кожного облікового запису.
|
||||
- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Live stream preview (редагування повідомлень)">
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення preview + `editMessageText`
|
||||
- групи/теми: повідомлення preview + `editMessageText`
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення preview (за замовчуванням: `true`, коли preview streaming активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення tool/progress повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли preview streaming активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення preview для прогресу інструментів — це короткі рядки "Працюємо...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати поведінці OpenClaw, випущеній у `v2026.4.22` і пізніше. Щоб зберегти редагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду перебігу роботи інструментів — це короткі рядки «Working...», які показуються під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати поведінці OpenClaw, випущеній у `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки перебігу роботи інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,47 +306,48 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду в Telegram вимикається, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремих повідомлень "Working...". Запити на схвалення, медіа-вміст і помилки й далі проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування прев’ю в Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання окремими повідомленнями "Working...". Запити на схвалення, медіа-вміст і помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно залишити лише редагування прев’ю відповіді, приховавши рядки стану прогресу інструментів.
|
||||
|
||||
<Note>
|
||||
Відповіді Telegram на вибрані цитати є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний механізм Telegram для відповідей із цитатою замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показувати короткі рядки "Working..." для такого звернення. Відповіді на поточне повідомлення без тексту вибраної цитати й далі зберігають потоковий попередній перегляд. Встановіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді з цитатою, або встановіть `streaming.preview.toolProgress: false`, щоб прийняти цей компроміс.
|
||||
Відповіді на вибрані цитати в Telegram є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний шлях відповіді на цитату Telegram замість редагування прев’ю відповіді, тому `streaming.preview.toolProgress` не може показати короткі рядки "Working..." для цього звернення. Відповіді на поточне повідомлення без тексту вибраної цитати все ще зберігають потокове прев’ю. Встановіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді на цитати, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс.
|
||||
</Note>
|
||||
|
||||
Для текстових відповідей:
|
||||
|
||||
- короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, тому видима часова позначка Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
- короткі прев’ю в DM/групі/темі: OpenClaw зберігає те саме повідомлення прев’ю і виконує фінальне редагування на місці, якщо після появи прев’ю не було надіслано видиме повідомлення, що не є прев’ю
|
||||
- прев’ю, після яких іде видимий вивід, що не є прев’ю: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення й очищає старіше прев’ю, тож фінальна відповідь з’являється після проміжного виводу
|
||||
- прев’ю, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає прев’ю, тож видима позначка часу Telegram відображає час завершення, а не час створення прев’ю
|
||||
|
||||
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення прев’ю.
|
||||
|
||||
Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
Потокове прев’ю відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік прев’ю, щоб уникнути подвійного потокового передавання.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
Потік міркувань тільки для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерації
|
||||
- `/reasoning stream` надсилає міркування в живе прев’ю під час генерації
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний варіант HTML">
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
|
||||
- Необроблений HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як простий текст.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
Прев’ю посилань увімкнені за замовчуванням, їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`.
|
||||
<Accordion title="Нативні команди та власні команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
Стандартні значення нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
Додайте користувацькі записи меню команд:
|
||||
Додайте власні записи меню команд:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -363,47 +364,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- назви нормалізуються (прибирається початковий `/`, переводяться в нижній регістр)
|
||||
- назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й логуються
|
||||
- власні команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються і записуються в журнал
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- власні команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill можуть працювати під час введення, навіть якщо не показані в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть і далі реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні/plugin-команди все ще можуть реєструватися, якщо налаштовані.
|
||||
|
||||
Поширені збої налаштування:
|
||||
Поширені помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` із `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд 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` із мережевими помилками/помилками fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `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 зупиняється перед опитуванням, тому це не повідомляється як помилка очищення Webhook.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
|
||||
|
||||
### Команди сполучення пристрою (Plugin `device-pair`)
|
||||
### Команди сполучення пристрою (`device-pair` plugin)
|
||||
|
||||
Коли Plugin `device-pair` встановлено:
|
||||
Коли встановлено `device-pair` plugin:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями дії)
|
||||
2. вставте код в iOS app
|
||||
3. `/pair pending` показує очікувані запити (включно з роллю/областями дії)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один очікуваний запит
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області дії bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролі, що не є оператором, усе ще потребують областей дії під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; неоператорські ролі все ще потребують областей дії під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роллю/областями дії/публічним ключем), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими даними авторизації (наприклад, роллю/областями дії/публічним ключем), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані кнопки">
|
||||
Налаштуйте область дії вбудованої клавіатури:
|
||||
Налаштуйте область дії inline-клавіатури:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -443,7 +444,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -463,7 +464,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Натискання зворотних викликів передаються агенту як текст:
|
||||
Натискання callback передаються агенту як текст:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
@ -471,15 +472,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Керування обмеженнями:
|
||||
Елементи керування доступом:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -487,16 +488,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують довільне повторне розв’язання SecretRef для кожного надсилання.
|
||||
Надсилання під час виконання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ситуативне повторне розв’язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги гілок відповідей">
|
||||
Telegram підтримує явні теги гілок відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги ланцюжків відповідей">
|
||||
Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що запустило обробку
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що запустило дію
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
@ -505,29 +506,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Коли гілки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до простої відповіді, якщо Telegram відхиляє цитату.
|
||||
Коли ланцюжки відповідей увімкнено і оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні гілки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються.
|
||||
Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка гілок">
|
||||
Форумні супергрупи:
|
||||
<Accordion title="Теми форуму та поведінка ланцюжків">
|
||||
Супергрупи форуму:
|
||||
|
||||
- ключі сеансів теми додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору тексту спрямовуються в гілку теми
|
||||
- шлях конфігурації теми:
|
||||
- ключі сесій теми додають `:topic:<threadId>`
|
||||
- відповіді й індикатор набору тексту спрямовуються в ланцюжок теми
|
||||
- шлях config теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все одно містять `message_thread_id`
|
||||
- надсилання повідомлень опускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все ще включають `message_thread_id`
|
||||
|
||||
Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише до теми й не успадковується з типових значень групи.
|
||||
Наслідування теми: записи теми наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` належить лише темі й не наслідується з типових значень групи.
|
||||
|
||||
**Маршрутизація агента для окремої теми**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад:
|
||||
**Маршрутизація агента для кожної теми**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -547,13 +548,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Після цього кожна тема має власний ключ сеансу: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Потім кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійна прив’язка тем ACP**: теми форуму можуть закріплювати сеанси ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID із кваліфікатором теми, наприклад `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
**Постійне прив’язування теми ACP**: Теми форуму можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з уточненням теми, наприклад `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
**Створення thread-bound ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються безпосередньо туди. OpenClaw закріплює підтвердження створення в темі. Потребує, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`).
|
||||
**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.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді у плоских сесіях; вони використовують ключі сесій з урахуванням ланцюжків лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідний config теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня як типове значення облікового запису або `direct.<chatId>.threadReplies` для одного DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -564,9 +565,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку
|
||||
- транскрипти вхідних голосових нотаток оформлюються як машинно згенерований,
|
||||
ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з обмеженням за згадкою й далі працюють.
|
||||
- транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований,
|
||||
недовірений текст; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тому голосові повідомлення з вимогою згадки продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -602,7 +603,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
|
||||
- статичний WEBP: завантажується й обробляється (placeholder `<media:sticker>`)
|
||||
- статичний WEBP: завантажується й обробляється (плейсхолдер `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
@ -618,7 +619,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики розпізнавання зображень.
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision.
|
||||
|
||||
Увімкнути дії зі стікерами:
|
||||
|
||||
@ -658,10 +659,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
<Accordion title="Reaction notifications">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw додає в чергу системні події на кшталт:
|
||||
Якщо ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -673,16 +674,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає thread IDs в оновленнях реакцій.
|
||||
- групи без форумів спрямовуються до сесії групового чату
|
||||
- групи-форуми спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID потоків в оновленнях реакцій.
|
||||
- нефорумні групи маршрутизуються до сесії групового чату
|
||||
- форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної вихідної теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ack-реакції">
|
||||
<Accordion title="Ack reactions">
|
||||
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
@ -695,17 +696,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує unicode emoji (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
- Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Записи конфігурації з подій і команд Telegram">
|
||||
<Accordion title="Config writes from Telegram events and commands">
|
||||
Записи конфігурації каналу ввімкнені типово (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
Записи, спричинені Telegram, включають:
|
||||
|
||||
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потрібне ввімкнення команди)
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команд)
|
||||
|
||||
Вимкнути:
|
||||
|
||||
@ -721,38 +722,38 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling проти webhook">
|
||||
Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; додатково `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling vs webhook">
|
||||
Типовий режим — long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON body перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі per-chat/per-topic bot lanes, що й long polling, тому повільні ходи агента не затримують delivery ACK Telegram.
|
||||
Режим webhook перевіряє захист запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/теми, які використовує long polling, тож повільні ходи агента не затримують delivery ACK Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби та цілі CLI">
|
||||
- `channels.telegram.textChunkLimit` типово дорівнює 4000.
|
||||
<Accordion title="Limits, retry, and CLI targets">
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає таймаут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного guard для вихідних текстових/typing запитів, щоб grammY не переривав доставку видимої відповіді до того, як зможуть спрацювати transport guard і fallback OpenClaw. Long polling усе ще використовує 45-секундний guard запиту `getUpdates`, щоб idle polls не залишалися покинутими безстроково.
|
||||
- `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; змінюйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків polling-stall.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
|
||||
- додатковий контекст reply/quote/forward наразі передається в отриманому вигляді.
|
||||
- Allowlist-и Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти бота обмежують налаштовані значення, нижчі за 60-секундний guard для вихідних text/typing запитів, щоб grammY не перервав доставку видимої відповіді до того, як зможуть спрацювати transport guard і fallback OpenClaw. Long polling усе ще використовує 45-секундний guard запиту `getUpdates`, щоб idle polls не покидалися безстроково.
|
||||
- `channels.telegram.pollingStallThresholdMs` типово має значення `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через polling-stall.
|
||||
- Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
|
||||
- Додатковий контекст reply/quote/forward наразі передається так, як отриманий.
|
||||
- Allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений safe-send retry для збоїв Telegram pre-connect, але не повторює неоднозначні post-send network envelopes, які можуть дублювати видимі повідомлення.
|
||||
- Конфігурація `channels.telegram.retry` застосовується до helpers надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений safe-send retry для pre-connect збоїв Telegram, але не повторює неоднозначні post-send мережеві envelopes, які можуть дублювати видимі повідомлення.
|
||||
|
||||
Ціль надсилання CLI може бути числовим chat ID або username:
|
||||
Ціль надсилання CLI може бути числовим ID чату або username:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують теми форумів:
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують форумні теми:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -767,36 +768,36 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для тем форумів (або використовуйте ціль `:topic:`)
|
||||
- `--thread-id` для форумних тем (або використайте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для inline keyboards, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media
|
||||
- `--presentation` з блоками `buttons` для inline keyboards, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту pinned delivery, коли бот може pin у цьому чаті
|
||||
- `--force-document` для надсилання вихідних зображень і GIF як документів замість стисненого photo або animated-media uploads
|
||||
|
||||
Обмеження дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec approvals у Telegram">
|
||||
Telegram підтримує exec approvals в DM approver-ів і може додатково публікувати prompts у початковому чаті або темі. Approver-и мають бути числовими Telegram user IDs.
|
||||
<Accordion title="Exec approvals in Telegram">
|
||||
Telegram підтримує exec approvals у DM затверджувачів і може додатково публікувати prompts у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного approver-а)
|
||||
- `channels.telegram.execApprovals.approvers` (fallback до числових owner IDs із `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (fallback до числових owner ID з `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver-ом. Перше схвалене pairing DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе одно працює без дублювання IDs у `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver. Перше схвалене DM pairing ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`.
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє в тему форуму, OpenClaw зберігає тему для prompt схвалення і follow-up. Exec approvals типово спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для approval prompt і подальшого повідомлення. Exec approvals типово спливають через 30 хвилин.
|
||||
|
||||
Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Approval IDs із префіксом `plugin:` визначаються через plugin approvals; інші спершу визначаються через exec approvals.
|
||||
Inline approval buttons також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Approval IDs з префіксом `plugin:` визначаються через plugin approvals; інші спершу визначаються через exec approvals.
|
||||
|
||||
Див. [Exec approvals](/uk/tools/exec-approvals).
|
||||
|
||||
@ -805,14 +806,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
## Керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або provider-а, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації:
|
||||
Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації:
|
||||
|
||||
| Ключ | Значення | Типово | Опис |
|
||||
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю пригнічує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. |
|
||||
| Ключ | Значення | Типово | Опис |
|
||||
| ----------------------------------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилок під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
Підтримуються перевизначення для облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -833,56 +834,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на групові повідомлення без згадки">
|
||||
<Accordion title="Bot does not respond to non mention group messages">
|
||||
|
||||
- Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість.
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові group IDs; wildcard `"*"` не можна перевірити на membership.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот узагалі не бачить групові повідомлення">
|
||||
<Accordion title="Bot not seeing group messages at all">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`)
|
||||
- перевірте membership бота в групі
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте логи: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або не працюють зовсім">
|
||||
<Accordion title="Commands work partially or not at all">
|
||||
|
||||
- авторизуйте вашу sender identity (pairing та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли group policy має значення `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в native menu забагато записів; зменште кількість plugin/skill/custom commands або вимкніть native menus
|
||||
- стартові виклики `deleteMyCommands` / `setMyCommands` і typing-виклики `sendChatAction` обмежені й повторюються один раз через transport fallback Telegram при request timeout. Постійні network/fetch errors зазвичай вказують на проблеми DNS/HTTPS-доступності до `api.telegram.org`
|
||||
- авторизуйте свою ідентичність відправника (pairing і/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menus
|
||||
- startup виклики `deleteMyCommands` / `setMyCommands` і typing виклики `sendChatAction` обмежені та повторюються один раз через transport fallback Telegram у разі timeout запиту. Постійні network/fetch помилки зазвичай вказують на проблеми досяжності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Запуск повідомляє про неавторизований токен">
|
||||
<Accordion title="Startup reports unauthorized token">
|
||||
|
||||
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого bot token.
|
||||
- Скопіюйте повторно або згенеруйте заново bot token у BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм auth; трактування цього як "no webhook exists" лише відклало б той самий збій bad-token до пізніших API calls.
|
||||
- `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте заново токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "Webhook не існує" лише відкладе ту саму помилку поганого токена до пізніших викликів API.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
<Accordion title="Нестабільність опитування або мережі">
|
||||
|
||||
- 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 замість ще одного контрольного виклику перед опитуванням. Все ще активний webhook проявляється як конфлікт `getUpdates`; після цього OpenClaw перебудовує транспорт Telegram і повторює очищення webhook.
|
||||
- Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення, нижчі за запобіжники вихідних запитів і запитів `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 також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартних змінних середовища proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ + власний fetch/proxy може спричиняти негайну поведінку переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу розв'язують `api.telegram.org` в IPv6; зламаний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
|
||||
- Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, тому виконавцю не потрібен другий `getMe` перед першим `getUpdates`.
|
||||
- Якщо `deleteWebhook` завершується з помилкою через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до long polling замість ще одного попереднього керувального виклику перед опитуванням. Все ще активний Webhook проявляється як конфлікт `getUpdates`; тоді OpenClaw перебудовує транспорт Telegram і повторює очищення Webhook.
|
||||
- Якщо сокети Telegram перезапускаються з коротким фіксованим інтервалом, перевірте, чи не є `channels.telegram.timeoutSeconds` занизьким; клієнти ботів обмежують налаштовані значення, нижчі за захисти вихідних запитів і запитів `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 також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` все ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища, а стандартних змінних середовища proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -890,8 +891,8 @@ channels:
|
||||
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, примусово задайте вибір сімейства:
|
||||
- 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, примусово задайте вибір сімейства:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -900,10 +901,10 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді діапазону для бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на іншу
|
||||
приватну/внутрішню/спеціальну адресу під час завантаження медіа, ви можете
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантаження медіа, ви можете
|
||||
увімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
@ -913,14 +914,18 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Та сама опція доступна для кожного облікового запису за адресою
|
||||
- Така сама опція доступна для кожного облікового запису за адресою
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy розв’язує медіахости Telegram у `198.18.x.x`, спершу залиште
|
||||
- Якщо ваш proxy розв'язує медіахости Telegram у `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
|
||||
RFC 2544 для бенчмаркінгу за замовчуванням.
|
||||
бенчмарків RFC 2544 за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти SSRF для медіа Telegram. Використовуйте це лише в довірених, контрольованих оператором середовищах proxy, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони синтезують приватні чи спеціальні відповіді поза діапазоном RFC 2544 для бенчмаркінгу. Залишайте це вимкненим для звичайного доступу Telegram через публічний інтернет.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює SSRF-захисти
|
||||
медіа Telegram. Використовуйте це лише для довірених середовищ proxy,
|
||||
керованих оператором, як-от Clash, Mihomo або маршрутизація fake-IP Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном бенчмарків
|
||||
RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення середовища (тимчасові):
|
||||
@ -937,24 +942,24 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting).
|
||||
Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Високоінформативні поля Telegram">
|
||||
<Accordion title="Найважливіші поля Telegram">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`)
|
||||
- схвалення exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки/відповіді: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot<TOKEN>`)
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
@ -963,7 +968,7 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити стандартну маршрутизацію явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язане
|
||||
@ -973,7 +978,7 @@ dig +short api.telegram.org AAAA
|
||||
Сполучіть користувача Telegram із Gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
Поведінка списку дозволів для груп і тем.
|
||||
</Card>
|
||||
<Card title="Маршрутизація каналів" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
@ -985,6 +990,6 @@ dig +short api.telegram.org AAAA
|
||||
Зіставляйте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами.
|
||||
Міжканальна діагностика.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user