chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
becbf6ea16
commit
6bfd1f98ce
File diff suppressed because it is too large
Load Diff
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Стан підтримки бота Telegram, можливості та конфігурація
|
||||
summary: Стан підтримки Telegram-бота, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T11:47:40Z"
|
||||
generated_at: "2026-04-29T12:06:06Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8bae9845e95669fe21d75694d81172bfb4fc6329b67ef232e7fe4cbf67b87958
|
||||
source_hash: 8db902132bd9b93deda2f951353dadc6ea2d4d76a59919cf1fb90f7e75615556
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово до production-використання для ботів у DM і групах через grammY. Режим довгого опитування є стандартним; режим Webhook є необов'язковим.
|
||||
Готове до продакшну для особистих повідомлень бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика DM для Telegram — сполучення.
|
||||
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
|
||||
Політика особистих повідомлень за замовчуванням для Telegram — створення пари.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
<Card title="Gateway configuration" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -29,14 +29,14 @@ x-i18n:
|
||||
## Швидке налаштування
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
<Step title="Create the bot token in BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
Запустіть `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Налаштуйте токен і політику DM">
|
||||
<Step title="Configure token and DM policy">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть Gateway.
|
||||
Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/змінних середовища, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть Gateway і схваліть перший DM">
|
||||
<Step title="Start gateway and approve first DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,82 +64,82 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди сполучення спливають через 1 годину.
|
||||
Коди створення пари спливають через 1 годину.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте бота до групи">
|
||||
Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
<Step title="Add the bot to a group">
|
||||
Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до своєї моделі доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервною змінною середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість груп">
|
||||
Боти Telegram стандартно використовують **Privacy Mode**, який обмежує, які повідомлення груп вони отримують.
|
||||
<Accordion title="Privacy mode and group visibility">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення групи, зробіть одне з такого:
|
||||
Якщо бот має бачити всі групові повідомлення, або:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи групи">
|
||||
Статус адміністратора контролюється в налаштуваннях групи Telegram.
|
||||
<Accordion title="Group permissions">
|
||||
Статус адміністратора керується в налаштуваннях групи Telegram.
|
||||
|
||||
Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі.
|
||||
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
<Accordion title="Helpful BotFather toggles">
|
||||
|
||||
- `/setjoingroups`, щоб дозволити/заборонити додавання до груп
|
||||
- `/setjoingroups` для дозволу/заборони додавання до груп
|
||||
- `/setprivacy` для поведінки видимості в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Контроль доступу й активація
|
||||
## Контроль доступу та активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика DM">
|
||||
<Tab title="DM policy">
|
||||
`channels.telegram.dmPolicy` керує доступом до особистих повідомлень:
|
||||
|
||||
- `pairing` (стандартно)
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім'я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` трактується як межа безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об'єднання все ще не містить явний wildcard.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв'язати (best-effort; потребує токена бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня розглядається як межа безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний список дозволів облікового запису після об’єднання все ще не містить явного шаблону `*`.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється перевіркою конфігурації.
|
||||
Під час налаштування запитуються лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи списку дозволів `@username`, запустіть `openclaw doctor --fix`, щоб розв’язати їх (найкраща спроба; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли списку дозволів зі сховища створення пари, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях зі списком дозволів (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення).
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх підтверджень створення пари).
|
||||
|
||||
Типова плутанина: схвалення сполучення DM не означає "цей відправник авторизований усюди".
|
||||
Сполучення надає доступ до DM. Якщо власник команд ще не існує, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все ще походить із явних allowlist у конфігурації.
|
||||
Якщо ви хочете "я авторизований один раз, і працюють і DM, і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
Типова плутанина: схвалення створення пари для особистих повідомлень не означає «цей відправник авторизований всюди».
|
||||
Створення пари надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене створення пари також задає `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення виконання мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все ще походить із явних списків дозволів у конфігурації.
|
||||
Якщо вам потрібно «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
1. Напишіть своєму боту в особисті повідомлення.
|
||||
2. Запустіть `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
Офіційний метод Bot API:
|
||||
@ -152,31 +152,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlist">
|
||||
<Tab title="Group policy and allowlists">
|
||||
Два елементи керування застосовуються разом:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає конфігурації `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
- `groups` налаштовано: діє як список дозволів (явні 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`.
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): автентифікація відправника в групі **не** успадковує схвалення зі сховища спарювання DM.
|
||||
Спарювання лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігурації `allowFrom`, а не до сховища спарювання.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища створення пари для особистих повідомлень.
|
||||
Створення пари залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища створення пари.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо середовища виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням відмовляє безпечно з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням закриває доступ через `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Приклад: дозволити лише конкретним користувачам в одній конкретній групі:
|
||||
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,17 +211,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
Типова помилка: `groupAllowFrom` не є списком дозволених груп Telegram.
|
||||
|
||||
- Додавайте від’ємні ID чатів груп Telegram або супергруп, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди в дозволеній групі можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
- Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг розмовляти з ботом.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Поведінка згадок">
|
||||
<Tab title="Mention behavior">
|
||||
Відповіді в групах за замовчуванням потребують згадки.
|
||||
|
||||
Згадка може надходити з:
|
||||
@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд на рівні сеансу:
|
||||
Перемикачі команд на рівні сесії:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сеансу. Для збереження використовуйте конфігурацію.
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію.
|
||||
|
||||
Приклад сталої конфігурації:
|
||||
|
||||
@ -252,31 +252,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Отримання ID групового чату:
|
||||
Як отримати ID групового чату:
|
||||
|
||||
- перешліть повідомлення з групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перевірте `getUpdates` Bot API
|
||||
- переслати групове повідомлення до `@userinfobot` / `@getidsbot`
|
||||
- або прочитати `chat.id` з `openclaw logs --follow`
|
||||
- або переглянути `getUpdates` Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Поведінка середовища виконання
|
||||
## Поведінка під час виконання
|
||||
|
||||
- Telegram належить процесу Gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали).
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільну оболонку каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сеансів, що враховують тред, і зберігає ID треду для відповідей.
|
||||
- Long polling використовує grammY runner із послідовністю для кожного чату/треду. Загальна конкурентність приймача runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищено всередині кожного процесу Gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший Gateway OpenClaw, скрипт або зовнішній poller, імовірно, використовує той самий токен.
|
||||
- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку polling під час тривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує read-receipt (`sendReadReceipts` не застосовується).
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми були ізольовані.
|
||||
- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують потік, і зберігає ID потоку для відповідей.
|
||||
- Довге опитування використовує grammY runner із послідовністю за чатом/потоком. Загальна паралельність приймача runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний опитувач міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній опитувач використовує той самий токен.
|
||||
- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеного сигналу активності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд прямої трансляції (редагування повідомлень)">
|
||||
<Accordion title="Live stream preview (message edits)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
@ -284,12 +284,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` є `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна трансляція попереднього перегляду)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх до `channels.telegram.streaming.mode`
|
||||
- `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли потоковий попередній перегляд активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Працюємо...", що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень планування або зведень патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і новіше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніше. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,16 +306,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення "Працюємо...". Запити на схвалення, медіа-вміст і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки стану прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення «Працюю...». Запити на схвалення, медіанавантаження та помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише залишити редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
Для відповідей лише текстом:
|
||||
|
||||
- короткі попередні перегляди DM/групи/теми: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу в Telegram відображала час завершення, а не час створення попереднього перегляду
|
||||
- короткі попередні перегляди DM/групи/теми: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тому видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Стримінг попереднього перегляду відокремлений від стримінгу блоків. Коли стримінг блоків явно ввімкнено для Telegram, OpenClaw пропускає стрим попереднього перегляду, щоб уникнути подвійного стримінгу.
|
||||
Потокове передавання попереднього перегляду відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
|
||||
|
||||
@ -326,21 +326,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та запасний варіант HTML">
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст.
|
||||
- Текст у стилі Markdown відтворюється як безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити збої розбору Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені за допомогою `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
|
||||
Нативні значення команд за замовчуванням:
|
||||
Типові значення нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
@ -361,47 +361,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- чинний шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- назви нормалізуються (прибирається початковий `/`, нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й записуються в журнал
|
||||
- конфлікти/дублікати пропускаються та записуються в журнал
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- команди Plugin/skill можуть усе ще працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди або команди 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` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `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` заблоковано.
|
||||
|
||||
### Команди сполучення пристрою (plugin `device-pair`)
|
||||
### Команди сполучення пристрою (Plugin `device-pair`)
|
||||
|
||||
Коли plugin `device-pair` встановлено:
|
||||
Коли встановлено Plugin `device-pair`:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список запитів, що очікують (включно з роллю/областями)
|
||||
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 мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, усе ще потребують областей під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний токен початкового завантаження. Вбудована передача початкового завантаження зберігає токен основного вузла в `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області доступу початкового завантаження мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролям, що не є операторами, усе ще потрібні області доступу з їхнім власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області/публічний ключ), попередній запит, що очікував, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані кнопки">
|
||||
Налаштуйте область inline-клавіатури:
|
||||
Налаштуйте область дії вбудованої клавіатури:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -433,7 +433,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Області:
|
||||
Області дії:
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -441,7 +441,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`.
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -475,9 +475,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Елементи керування доступом:
|
||||
Засоби керування доступом:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -485,16 +485,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціальне повторне розв’язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
Семантика видалення реакції: [/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` керує обробкою:
|
||||
@ -503,17 +503,17 @@ 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>`
|
||||
- відповіді та індикатор набору спрямовуються в потік теми
|
||||
- шлях конфігурації теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
@ -522,10 +522,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- надсилання повідомлень пропускає `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` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -545,26 +545,26 @@ 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 через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"`, а також ID з уточненням теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
**Створення ACP, прив’язане до ланцюжка, з чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
**Прив’язаний до потоку запуск ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесій з урахуванням ланцюжків.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сеансів з урахуванням потоку.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Аудіо, відео та стікери">
|
||||
### Аудіоповідомлення
|
||||
|
||||
Telegram розрізняє голосові нотатки й аудіофайли.
|
||||
Telegram розрізняє голосові нотатки та аудіофайли.
|
||||
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосову нотатку
|
||||
- транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований,
|
||||
ненадійний текст; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тому голосові повідомлення, обмежені згадками, продовжують працювати.
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку
|
||||
- розшифрування вхідних голосових нотаток оформлюються в контексті агента як згенерований машиною,
|
||||
недовірений текст; виявлення згадки все ще використовує сире
|
||||
розшифрування, тому голосові повідомлення з вимогою згадки продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -580,7 +580,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Відеоповідомлення
|
||||
|
||||
Telegram розрізняє відеофайли й відеонотатки.
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -600,7 +600,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
|
||||
- статичний WEBP: завантажується й обробляється (заповнювач `<media:sticker>`)
|
||||
- статичний WEBP: завантажується та обробляється (заповнювач `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
@ -616,7 +616,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору.
|
||||
|
||||
Увімкнути дії зі стікерами:
|
||||
|
||||
@ -657,7 +657,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень).
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від навантажень повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
@ -665,44 +665,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Конфігурація:
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`)
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`)
|
||||
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувача на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень).
|
||||
- Події реакцій усе ще дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори гілок в оновленнях реакцій.
|
||||
- нефорумні групи спрямовуються до сеансу групового чату
|
||||
- форумні групи спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID гілок в оновленнях реакцій.
|
||||
- групи нефорумного типу скеровуються до сеансу групового чату
|
||||
- форумні групи скеровуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Реакції підтвердження">
|
||||
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
Порядок вирішення:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує emoji Unicode (наприклад, "👀").
|
||||
- Telegram очікує unicode-емодзі (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Записи конфігурації з подій і команд Telegram">
|
||||
Записи конфігурації каналу ввімкнені типово (`configWrites !== false`).
|
||||
Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`).
|
||||
|
||||
Записи, спричинені Telegram, включають:
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команд)
|
||||
|
||||
Вимкнення:
|
||||
@ -719,29 +719,29 @@ 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 проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим Webhook перевіряє захисти запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, що використовуються long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
Режим webhook перевіряє захисні умови запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/теми, що й long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби й цілі CLI">
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зупинку polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий.
|
||||
- allowlist-и Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
<Accordion title="Ліміти, повтори та цілі CLI">
|
||||
- `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується значення за замовчуванням grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зупинку polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
|
||||
- додатковий контекст reply/quote/forward наразі передається як отримано.
|
||||
- allowlists Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для помилок Telegram до підключення, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення.
|
||||
- Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений безпечний повтор надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
|
||||
@ -765,50 +765,50 @@ 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` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати повідомлення в цьому чаті
|
||||
- `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених фото або завантажень анімованих медіа
|
||||
- `--presentation` з блоками `buttons` для inline keyboards, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених фото або завантажень animated-media
|
||||
|
||||
Обмеження дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Схвалення exec у Telegram">
|
||||
Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM затверджувачів і може необов’язково публікувати prompts у початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача)
|
||||
- `channels.telegram.execApprovals.approvers` (відступає до числових ID власників з `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (відступає до числових ID власників із `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене спарювання DM початково налаштовує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може розмовляти з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось затверджувачем exec. Перше схвалене створення пари DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`.
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення і подальшого повідомлення. Схвалення exec типово спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для prompt затвердження та подальшого повідомлення. Підтвердження exec за замовчуванням спливають через 30 хвилин.
|
||||
|
||||
Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення plugin; інші спочатку визначаються через схвалення exec.
|
||||
Inline-кнопки затвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID затвердження з префіксом `plugin:` вирішуються через затвердження plugin; інші спершу вирішуються через підтвердження exec.
|
||||
|
||||
Див. [Схвалення exec](/uk/tools/exec-approvals).
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, 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` | число (мс) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для кожного облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
|
||||
@ -835,49 +835,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і знову додайте бота до групи
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сеансу: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот взагалі не бачить групові повідомлення">
|
||||
<Accordion title="Бот узагалі не бачить групових повідомлень">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`)
|
||||
- коли існує `channels.telegram.groups`, групу потрібно вказати (або включити `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або не працюють зовсім">
|
||||
<Accordion title="Команди працюють частково або не працюють узагалі">
|
||||
|
||||
- авторизуйте ідентичність відправника (спарювання та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з мережевими/ fetch-помилками зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
- авторизуйте свою ідентичність відправника (створення пари та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menus
|
||||
- `setMyCommands failed` з мережевими/fetch помилками зазвичай указує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований токен">
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований token">
|
||||
|
||||
- `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота.
|
||||
- Знову скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б ту саму помилку неправильного токена до пізніших викликів API.
|
||||
- Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо очищення вже виконано.
|
||||
- `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` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий token до наступних викликів API.
|
||||
- Якщо `deleteWebhook` зазнає збою через тимчасову мережеву помилку під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо очищення вже виконано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
|
||||
- Node 22+ і користувацький fetch/проксі можуть спричиняти негайну поведінку переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу визначають `api.telegram.org` як IPv6; зламаний вихід IPv6 може спричиняти переривчасті збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за типових налаштувань.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли тривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми проксі, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`.
|
||||
- Telegram також враховує env проксі процесу для транспорту Bot API, включно з `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхніми варіантами в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований проксі OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартного env проксі немає, Telegram також використовує цей URL для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ і власний fetch/proxy можуть спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі hosts спершу вирішують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної liveness long-poll за замовчуванням.
|
||||
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис polling не завершив `getUpdates` після startup grace або коли його остання успішна активність polling transport застаріла.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш host усе одно повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай указують на проблеми proxy, DNS, IPv6 або TLS egress між host і `api.telegram.org`.
|
||||
- Telegram також враховує process proxy env для транспорту Bot API, включно з `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхніми варіантами в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для service environment і стандартного proxy env немає, Telegram також використовує цей URL для транспорту Bot API.
|
||||
- На VPS hosts з нестабільним прямим egress/TLS скеровуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -885,8 +886,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ типово використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства:
|
||||
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або він явно краще працює з поведінкою лише IPv4, примусово задайте вибір family:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -895,10 +896,10 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді діапазону тестування за RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді з benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий проксі переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете
|
||||
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, можна
|
||||
увімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
@ -908,17 +909,17 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Те саме вибіркове ввімкнення доступне для кожного облікового запису за адресою
|
||||
- Такий самий opt-in доступний для кожного облікового запису за адресою
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш проксі резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
|
||||
тестування RFC 2544 за замовчуванням.
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон
|
||||
RFC 2544 за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram
|
||||
від SSRF. Використовуйте це лише в довірених середовищах проксі, керованих оператором,
|
||||
як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
|
||||
синтезують приватні або спеціального призначення відповіді поза діапазоном тестування
|
||||
від SSRF. Використовуйте це лише для довірених, контрольованих оператором проксі-середовищ,
|
||||
таких як fake-IP routing у Clash, Mihomo або Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза benchmark-діапазоном
|
||||
RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет.
|
||||
</Warning>
|
||||
|
||||
@ -926,7 +927,7 @@ channels:
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Перевірте відповіді DNS:
|
||||
- Перевірте DNS-відповіді:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -936,24 +937,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="High-signal Telegram fields">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- схвалення виконання: `execApprovals`, `accounts.*.execApprovals`
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`)
|
||||
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки обговорень/відповіді: `replyToMode`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- streaming: `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`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
@ -962,28 +963,28 @@ 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>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Сполучіть користувача Telegram із Gateway.
|
||||
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
|
||||
Зв’яжіть користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка списку дозволених груп і тем.
|
||||
<Card title="Groups" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
</Card>
|
||||
<Card title="Маршрутизація каналів" icon="route" href="/uk/channels/channel-routing">
|
||||
<Card title="Channel routing" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
</Card>
|
||||
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і посилення захисту.
|
||||
<Card title="Security" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і зміцнення захисту.
|
||||
</Card>
|
||||
<Card title="Маршрутизація кількох агентів" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставляйте групи й теми з агентами.
|
||||
<Card title="Multi-agent routing" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Усунення проблем" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика.
|
||||
<Card title="Troubleshooting" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user