chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
fe08f6500e
commit
2d392d378a
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook-ами
|
||||
summary: Статус підтримки, можливості та конфігурація бота Telegram
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Статус підтримки бота Telegram, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T05:36:20Z"
|
||||
generated_at: "2026-04-26T22:47:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b7d269b15bc2d377fa45f0516e435517ed366c0216d0bc31fe4f4bc080a6c726
|
||||
source_hash: be2af133453fa0cce99c6137077206a0f83d95a62594bf6d8e25d94d1b9c56cd
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Готовий до продакшн-використання для DM бота та груп через grammY. Long polling — режим за замовчуванням; режим Webhook — необов’язковий.
|
||||
Готово до продакшну для DM бота та груп через grammY. Довге опитування — типовий режим; режим Webhook — необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Зв’язування" icon="link" href="/uk/channels/pairing">
|
||||
Типова політика DM для Telegram — зв’язування.
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Типова політика DM для Telegram — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення проблем каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -30,7 +30,7 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що хендл точно `@BotFather`).
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я користувача точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
|
||||
@ -51,7 +51,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервне значення через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням).
|
||||
Резервне значення через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише для типового облікового запису).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
@ -64,7 +64,7 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди зв’язування дійсні протягом 1 години.
|
||||
Коди сполучення дійсні протягом 1 години.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -74,21 +74,21 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням з env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням із змінної середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису.
|
||||
</Note>
|
||||
|
||||
## Налаштування з боку Telegram
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим конфіденційності та видимість у групах">
|
||||
За замовчуванням боти Telegram працюють у **Privacy Mode**, що обмежує, які повідомлення в групах вони отримують.
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Для ботів Telegram типовим є **Privacy Mode**, який обмежує, які повідомлення в групах вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого:
|
||||
|
||||
- вимкніть режим конфіденційності через `/setprivacy`, або
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після зміни режиму конфіденційності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -102,7 +102,7 @@ openclaw pairing approve telegram <CODE>
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
|
||||
- `/setjoingroups` — дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` — поведінка видимості в групах
|
||||
- `/setprivacy` — керування видимістю в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -113,64 +113,64 @@ openclaw pairing approve telegram <CODE>
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `pairing` (типово)
|
||||
- `allowlist` (потрібен щонайменше один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config.
|
||||
Під час налаштування запитуються лише числові ID користувачів.
|
||||
Якщо ви оновилися й ваша config містить записи allowlist у вигляді `@username`, виконайте `openclaw doctor --fix`, щоб перетворити їх (best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви раніше покладалися на файли allowlist у pairing-store, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для сценаріїв allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` підтримуються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється під час валідації конфігурації.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб їх виправити (best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви раніше покладалися на файли allowlist зі сховища pairing-store, `openclaw doctor --fix` може відновити записи до `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів із одним власником надавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень зв’язування).
|
||||
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалась у конфігурації (а не залежала від попередніх схвалень сполучення).
|
||||
|
||||
Поширена плутанина: схвалення зв’язування DM не означає, що «цей відправник авторизований усюди».
|
||||
Зв’язування надає доступ лише до DM. Авторизація відправника в групах усе ще визначається явними allowlist у config.
|
||||
Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`.
|
||||
Поширена плутанина: схвалення сполучення для DM не означає, що «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ лише до DM. Авторизація відправників у групах, як і раніше, походить з явних allowlist у конфігурації.
|
||||
Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніший спосіб (без стороннього бота):
|
||||
|
||||
1. Надішліть DM своєму боту.
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
Офіційний метод через Bot API:
|
||||
Офіційний спосіб через Bot API:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlist">
|
||||
Разом застосовуються два елементи керування:
|
||||
Разом застосовуються два механізми керування:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає config `groups`:
|
||||
- немає конфігурації `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`)
|
||||
- з `groupPolicy: "allowlist"` (типово): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `allowlist` (типово)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує резервне значення з `allowFrom`.
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram використовує резервне значення з `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються).
|
||||
Не додавайте ID чатів Telegram group або supergroup у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення DM із pairing-store.
|
||||
Зв’язування залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з config `allowFrom`, а не pairing store.
|
||||
Практичний шаблон для ботів із одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в режимі fail-closed з `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно.
|
||||
Не вказуйте ID груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються під час авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища pairing-store для DM.
|
||||
Сполучення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для конкретної групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з `allowFrom` у конфігурації, а не зі сховища pairing-store.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте потрібні групи через `channels.telegram.groups`.
|
||||
Примітка щодо виконання: якщо `channels.telegram` повністю відсутній, під час виконання типовим буде fail-closed `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
@ -209,31 +209,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram.
|
||||
|
||||
- Додавайте від’ємні ID Telegram group або supergroup, як-от `-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="Поведінка згадування">
|
||||
У групах відповіді типово потребують згадування.
|
||||
|
||||
Згадка може надходити з:
|
||||
Згадування може надходити з:
|
||||
|
||||
- нативної згадки `@botusername`, або
|
||||
- шаблонів згадки в:
|
||||
- шаблонів згадування в:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд на рівні сесії:
|
||||
Перемикачі команд рівня сесії:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
Вони оновлюють лише стан сесії. Для постійного збереження використовуйте конфігурацію.
|
||||
|
||||
Приклад сталої config:
|
||||
Приклад постійної конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -247,44 +247,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Отримання ID групового чату:
|
||||
Як отримати ID групового чату:
|
||||
|
||||
- перешліть повідомлення з групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перевірте Bot API `getUpdates`
|
||||
- або прочитайте `chat.id` у `openclaw logs --follow`
|
||||
- або перегляньте Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Поведінка runtime
|
||||
## Поведінка під час виконання
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються до спільного конверта каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Сесії груп ізольовані за ID групи. Для forum topics додається `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії, що враховують thread, і зберігає ID thread для відповідей.
|
||||
- Long polling використовує grammY runner із послідовною обробкою для кожного чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений у межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски watchdog для long polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні й далі виникають хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і може бути від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Сесії груп ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх за допомогою ключів сесії з урахуванням потоку та зберігає ID потоку для відповідей.
|
||||
- Довге опитування використовує grammY runner з послідовністю на рівні чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене в межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски watchdog для довгого опитування типово спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs`, лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник можливостей
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
<Accordion title="Попередній перегляд живого потоку (редагування повідомлень)">
|
||||
OpenClaw може передавати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (типово: `partial`)
|
||||
- `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення tool/progress повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активне preview streaming)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.toolProgress` визначає, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (типово: `true`, коли активний попередній перегляд потоку)
|
||||
- застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` визначаються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду tool-progress — це короткі рядки «Працюю...», які показуються під час виконання інструментів, наприклад під час виконання команд, читання файлів, оновлень планування або зведень патчів. У Telegram вони увімкнені за замовчуванням, щоб відповідати випущеній поведінці OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки tool-progress, задайте:
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Working...», що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень плану або підсумків патчів. У Telegram вони типово ввімкнені, щоб відповідати поведінці випущених версій OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -301,45 +301,45 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки статусу tool-progress.
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- DM: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- group/topic: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- короткі попередні перегляди в DM/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, щоб видимий часовий штамп у Telegram відображав час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад, з медіавмістом) OpenClaw використовує резервну звичайну фінальну доставку, а потім прибирає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, корисних навантажень із медіа) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду.
|
||||
|
||||
Preview streaming відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного стримінгу.
|
||||
Потоковий попередній перегляд відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично використовує резервний варіант `sendMessage` + `editMessageText`.
|
||||
Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично переходить на `sendMessage` + `editMessageText`.
|
||||
|
||||
Потік reasoning лише для Telegram:
|
||||
Потік міркування лише для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає reasoning у live preview під час генерації
|
||||
- фінальна відповідь надсилається без тексту reasoning
|
||||
- `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерації
|
||||
- фінальна відповідь надсилається без тексту міркування
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
<Accordion title="Форматування та резервний варіант HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown відтворюється як HTML, безпечний для Telegram.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram.
|
||||
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
|
||||
- Необроблений HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередній перегляд посилань увімкнений за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`.
|
||||
Попередній перегляд посилань увімкнено типово; його можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`.
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
|
||||
Типові налаштування нативних команд:
|
||||
Типові значення для нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
Додайте власні пункти меню команд:
|
||||
Додайте користувацькі записи до меню команд:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -356,40 +356,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- імена нормалізуються (прибирається початковий `/`, перетворюються на нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються та записуються в журнал
|
||||
- конфлікти/дублікати пропускаються та журналюються
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди — це лише пункти меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills все одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram
|
||||
- користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills можуть і далі працювати під час ручного введення, навіть якщо вони не показані в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin можуть і далі реєструватися, якщо це налаштовано.
|
||||
|
||||
Поширені збої налаштування:
|
||||
Поширені помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене навіть після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблокований.
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене після скорочення; зменште кількість користувацьких команд/команд Plugin/Skills або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані.
|
||||
|
||||
### Команди зв’язування пристрою (`device-pair` Plugin)
|
||||
### Команди сполучення пристроїв (Plugin `device-pair`)
|
||||
|
||||
Коли встановлено Plugin `device-pair`:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список очікуваних запитів (включно з роллю/scopes)
|
||||
3. `/pair pending` показує список незавершених запитів (включно з роллю/scopes)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один очікуваний запит
|
||||
- `/pair approve`, коли є лише один незавершений запит
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен первинного Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролям, що не є оператором, усе ще потрібні scopes під префіксом їхньої власної ролі.
|
||||
Код налаштування містить короткочасний bootstrap token. Вбудована передача bootstrap зберігає токен основного Node на `scopes: []`; будь-який переданий operator token залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope використовують префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є оператором, як і раніше потрібні scopes під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторно надсилає запит зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/scopes/public key), попередній незавершений запит замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
|
||||
|
||||
Докладніше: [Зв’язування](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -432,7 +432,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `dm`
|
||||
- `group`
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `allowlist` (типово)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` відповідає `inlineButtons: "all"`.
|
||||
|
||||
@ -443,7 +443,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
action: "send",
|
||||
channel: "telegram",
|
||||
to: "123456789",
|
||||
message: "Оберіть варіант:",
|
||||
message: "Виберіть варіант:",
|
||||
buttons: [
|
||||
[
|
||||
{ text: "Так", callback_data: "yes" },
|
||||
@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дії з повідомленнями Telegram для агентів і автоматизації">
|
||||
<Accordion title="Дії повідомлень Telegram для агентів та автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
@ -470,55 +470,55 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Керування обмеженнями:
|
||||
Керування доступом:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
- `channels.telegram.actions.sticker` (типово: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час runtime використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання.
|
||||
Примітка: `edit` і `topic-create` наразі типово ввімкнені й не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги ланцюжків відповідей">
|
||||
Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги потоків відповідей">
|
||||
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` — відповідь на повідомлення, що спричинило спрацювання
|
||||
- `[[reply_to:<id>]]` — відповідь на конкретний ID повідомлення Telegram
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що спричинило дію
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
|
||||
- `off` (за замовчуванням)
|
||||
- `off` (типово)
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Коли ланцюжки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує текст нативної цитати до 1024 кодових одиниць UTF-16, тому довші повідомлення цитуються з початку й використовують резервний звичайний reply, якщо Telegram відхиляє цитату.
|
||||
Коли потоки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати до 1024 кодових одиниць UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форумні теми та поведінка потоків">
|
||||
Forum supergroup:
|
||||
<Accordion title="Теми форуму та поведінка потоків">
|
||||
Супергрупи форуму:
|
||||
|
||||
- ключі сесії теми доповнюються `:topic:<threadId>`
|
||||
- відповіді й індикація набору тексту спрямовуються в потік теми
|
||||
- шлях config теми:
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору спрямовуються в потік теми
|
||||
- шлях конфігурації теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії індикації набору тексту все одно включають `message_thread_id`
|
||||
- дії індикатора набору все одно містять `message_thread_id`
|
||||
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` призначений лише для тем і не успадковується з типових налаштувань групи.
|
||||
`agentId` призначений лише для тем і не успадковується з типових значень групи.
|
||||
|
||||
**Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агента для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -529,7 +529,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Загальна тема → основний агент
|
||||
"3": { agentId: "zu" }, // Тема розробки → агент zu
|
||||
"5": { agentId: "coder" } // Огляд коду → агент coder
|
||||
"5": { agentId: "coder" } // Перевірка коду → агент coder
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -538,13 +538,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**: Forum topics можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми, як-от `-1001234567890:topic:42`). Наразі це обмежено forum topics у groups/supergroups. Див. [ACP Agents](/uk/tools/acp-agents).
|
||||
**Постійне прив’язування тем ACP**: Теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми на кшталт `-1001234567890:topic:42`). Наразі це обмежено темами форумів у групах/супергрупах. Див. [ACP Agents](/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, але використовують ключі сесії з урахуванням thread.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням потоку.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -553,11 +553,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Telegram розрізняє голосові повідомлення та аудіофайли.
|
||||
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- типово: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення
|
||||
- вхідні транскрипти голосових повідомлень оформлюються в контексті агента як машинно згенерований,
|
||||
недовірений текст; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тож голосові повідомлення з обмеженням за згадкою продовжують працювати.
|
||||
- транскрипти вхідних голосових повідомлень оформлюються в контексті агента як машинно згенерований,
|
||||
недовірений текст; виявлення згадувань усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з обмеженням за згадуванням продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -573,7 +573,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Відеоповідомлення
|
||||
|
||||
Telegram розрізняє відеофайли та video notes.
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -587,7 +587,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Video notes не підтримують підписи; наданий текст повідомлення надсилається окремо.
|
||||
Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо.
|
||||
|
||||
### Стікери
|
||||
|
||||
@ -609,9 +609,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
|
||||
Увімкнення дій зі стікерами:
|
||||
Увімкніть дії зі стікерами:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -642,7 +642,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
{
|
||||
action: "sticker-search",
|
||||
channel: "telegram",
|
||||
query: "кіт махає",
|
||||
query: "cat waving",
|
||||
limit: 5,
|
||||
}
|
||||
```
|
||||
@ -650,24 +650,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисних навантажень повідомлень).
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень).
|
||||
|
||||
Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
Коли цю функцію ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
- `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 42`
|
||||
|
||||
Config:
|
||||
Конфігурація:
|
||||
|
||||
- `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` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе ще дотримуються керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Події реакцій усе одно враховують механізми керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID потоку в оновленнях реакцій.
|
||||
- групи не forum маршрутизуються до сесії групового чату
|
||||
- forum groups маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- у нефорумних групах маршрутизація йде до сесії групового чату
|
||||
- у форумних групах маршрутизація йде до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включають `message_reaction`.
|
||||
|
||||
@ -685,13 +685,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує емодзі Unicode (наприклад, "👀").
|
||||
- Telegram очікує Unicode-емодзі (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Записи config із подій і команд Telegram">
|
||||
Записи config каналу увімкнені за замовчуванням (`configWrites !== false`).
|
||||
<Accordion title="Запис конфігурації з подій і команд Telegram">
|
||||
Запис конфігурації каналу типово ввімкнений (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
@ -712,38 +712,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="Довге опитування чи Webhook">
|
||||
Типово використовується довге опитування. Для режиму 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 перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw асинхронно обробляє оновлення через ті самі бот-черги для кожного чату/теми, що використовуються в long polling, тож повільні цикли агента не затримують ACK доставки Telegram.
|
||||
У режимі Webhook перед поверненням `200` до Telegram виконується перевірка захисту запиту, секретного токена Telegram і JSON-тіла.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота на рівні чату/теми, що й для довгого опитування, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби та цілі CLI">
|
||||
<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` вимикає.
|
||||
- Додатковий контекст reply/quote/forward наразі передається в отриманому вигляді.
|
||||
- Telegram allowlist насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіафайлів Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, використовується типове значення grammY).
|
||||
- Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання опитування.
|
||||
- Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає її.
|
||||
- Додатковий контекст reply/quote/forward наразі передається як отримано.
|
||||
- Allowlist у Telegram насамперед визначають, хто може викликати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Config `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API.
|
||||
- Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API.
|
||||
|
||||
Ціллю надсилання CLI може бути числовий ID чату або ім’я користувача:
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують forum topics:
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -758,50 +758,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для forum topics (або використовуйте ціль `:topic:`)
|
||||
- `--thread-id` для тем форуму (або використовуйте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
Надсилання в Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для вбудованих клавіатур, якщо це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, якщо бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа
|
||||
- `--presentation` із блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, якщо бот може закріплювати повідомлення в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фотографій або завантажень анімованих медіа
|
||||
|
||||
Керування обмеженнями дій:
|
||||
Керування діями:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання увімкненим
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Погодження exec у Telegram">
|
||||
Telegram підтримує погодження exec у DM погоджувачів і за потреби може публікувати запити в початковому чаті або темі. Погоджувачі мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Схвалення exec у Telegram">
|
||||
Telegram підтримує схвалення exec у DM схвалювачів і може додатково публікувати запити в початковому чаті або темі. Схвалювачами мають бути числові ID користувачів Telegram.
|
||||
|
||||
Шлях config:
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного погоджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (використовує резервне значення з числових owner ID із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного схвалювача)
|
||||
- `channels.telegram.execApprovals.approvers` (використовує як резервне значення числові ID власників із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених groups/topics. Коли запит потрапляє у forum topic, OpenClaw зберігає тему для запиту на погодження та подальших повідомлень. За замовчуванням погодження exec спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на схвалення та подальших повідомлень. Типово схвалення exec закінчуються через 30 хвилин.
|
||||
|
||||
Вбудовані кнопки погодження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID погоджень із префіксом `plugin:` визначаються через погодження Plugin; інші спочатку визначаються через погодження exec.
|
||||
Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення Plugin; інші спочатку визначаються через схвалення exec.
|
||||
|
||||
Див. [Погодження exec](/uk/tools/exec-approvals).
|
||||
Див. [Схвалення exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Керування відповідями на помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цією поведінкою керують два ключі config:
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації:
|
||||
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `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` | Мінімальний час між відповідями з помилками в одному й тому самому чаті. Запобігає спаму помилок під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів config Telegram).
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -811,7 +811,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
errorCooldownMs: 120000,
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
errorPolicy: "silent", // пригнічує помилки в цій групі
|
||||
errorPolicy: "silent", // пригнічувати помилки в цій групі
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -822,42 +822,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## Усунення проблем
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на повідомлення групи без згадки">
|
||||
<Accordion title="Бот не відповідає на повідомлення в групі без згадування">
|
||||
|
||||
- Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість.
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть бота й додайте його знову до групи
|
||||
- `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` неможливо перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
- потім видаліть і знову додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує повідомлення в групі без згадування.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; членство для шаблону `"*"` перевірити не можна.
|
||||
- швидка перевірка сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот узагалі не бачить повідомлення групи">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана в списку (або має бути `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або має бути `"*"`)
|
||||
- перевірте, що бот є учасником групи
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або не працюють взагалі">
|
||||
<Accordion title="Команди працюють частково або не працюють зовсім">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (pairing та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню занадто багато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми з досяжністю DNS/HTTPS до `api.telegram.org`
|
||||
- авторизуйте свою особу відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість користувацьких команд/команд Plugin/Skills або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми з доступністю DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
<Accordion title="Нестабільність опитування або мережі">
|
||||
|
||||
- Node 22+ + custom fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку визначають `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює спроби для них як для відновлюваних мережевих помилок.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і заново будує транспорт Telegram після 120 секунд без завершеної перевірки живучості long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` працюють справно, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ разом із кастомним fetch/proxy може спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку визначають `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти переривчасті збої Telegram API.
|
||||
- Якщо в журналах є `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці спроби як відновлювані мережеві помилки.
|
||||
- Якщо в журналах є `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки живучості довгого опитування за типовим налаштуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` є здоровими, але ваш хост усе ще повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або вихідним TLS між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим вихідним трафіком/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -865,8 +865,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, примусово задайте вибір сімейства:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -875,10 +875,10 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону тестів RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
transparent proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете
|
||||
- Відповіді діапазону RFC 2544 для бенчмарків (`198.18.0.0/15`) уже дозволені
|
||||
типово для завантажень медіа Telegram. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціальну адресу під час завантаження медіа, можна
|
||||
явно ввімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
@ -891,21 +891,21 @@ channels:
|
||||
- Такий самий явний параметр доступний для окремого облікового запису в
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Telegram media вже дозволяє діапазон тестів RFC 2544
|
||||
за замовчуванням.
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже типово дозволяють
|
||||
діапазон RFC 2544 для бенчмарків.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
|
||||
media від SSRF. Використовуйте це лише в довірених керованих оператором
|
||||
середовищах proxy, таких як Clash, Mihomo або Surge fake-IP routing, коли вони
|
||||
синтезують приватні або спеціальні відповіді поза діапазоном тестів RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте це вимкненим.
|
||||
media SSRF. Використовуйте його лише в довірених керованих оператором
|
||||
середовищах proxy, як-от Clash, Mihomo або Surge з маршрутизацією fake-IP, коли вони
|
||||
синтезують приватні або спеціальні відповіді поза діапазоном бенчмарку RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте цей параметр вимкненим.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення через змінні середовища (тимчасово):
|
||||
- `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
|
||||
@ -917,21 +917,21 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
Більше довідки: [Усунення проблем каналу](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник config
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [Configuration reference - Telegram](/uk/gateway/config-channels#telegram).
|
||||
Основний довідник: [Довідник конфігурації - 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`
|
||||
- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
@ -940,26 +940,26 @@ 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="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
З’єднати користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
</Card>
|
||||
<Card title="Маршрутизація каналів" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
<Card title="Маршрутизація каналу" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизація вхідних повідомлень до агентів.
|
||||
</Card>
|
||||
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і посилення захисту.
|
||||
</Card>
|
||||
<Card title="Маршрутизація кількох агентів" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставляйте групи й теми з агентами.
|
||||
Призначення груп і тем агентам.
|
||||
</Card>
|
||||
<Card title="Усунення проблем" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика.
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Пояснення того, як працюють streaming або chunking у каналах
|
||||
- Зміна поведінки потокового передавання блоків або chunking каналу
|
||||
- Налагодження дубльованих/передчасних відповідей блоками або потокового передавання попереднього перегляду каналу
|
||||
summary: Поведінка Streaming + chunking (відповіді блоками, потокове передавання попереднього перегляду каналу, зіставлення режимів)
|
||||
title: Streaming і chunking
|
||||
- Пояснення того, як працює потокова передача або розбиття на фрагменти в каналах
|
||||
- Зміна поведінки блокової потокової передачі або розбиття каналу на фрагменти
|
||||
- Налагодження дубльованих/передчасних блокових відповідей або потокової передачі попереднього перегляду каналу
|
||||
summary: Поведінка потокової передачі + розбиття на фрагменти (блокові відповіді, потокова передача попереднього перегляду каналу, зіставлення режимів)
|
||||
title: Потокова передача та розбиття на фрагменти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T12:04:27Z"
|
||||
generated_at: "2026-04-26T22:47:47Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ba308b79b12886f3a1bc36bc277e3df0e2b9c6018aa260b432ccea89a235819f
|
||||
source_hash: 7143421c98e8f4523e0f63653965ab0f63364d83f1073a6752385712551ec818
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw має два окремі рівні streaming:
|
||||
OpenClaw має два окремі шари потокової передачі:
|
||||
|
||||
- **Block streaming (канали):** надсилання завершених **блоків**, поки помічник пише. Це звичайні повідомлення каналу (не token deltas).
|
||||
- **Preview streaming (Telegram/Discord/Slack):** оновлення тимчасового **повідомлення попереднього перегляду** під час генерації.
|
||||
- **Блокова потокова передача (канали):** надсилає завершені **блоки**, коли помічник їх пише. Це звичайні повідомлення каналу (не дельти токенів).
|
||||
- **Потокова передача попереднього перегляду (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації.
|
||||
|
||||
Справжнього streaming із token deltas до повідомлень каналу наразі **немає**. Preview streaming працює на рівні повідомлень (надсилання + редагування/додавання).
|
||||
Справжньої потокової передачі дельт токенів у повідомлення каналу наразі **немає**. Потокова передача попереднього перегляду базується на повідомленнях (надсилання + редагування/додавання).
|
||||
|
||||
## Block streaming (повідомлення каналу)
|
||||
## Блокова потокова передача (повідомлення каналу)
|
||||
|
||||
Block streaming надсилає вихідні дані помічника грубими порціями в міру їх появи.
|
||||
Блокова потокова передача надсилає вивід помічника великими фрагментами в міру його появи.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -35,99 +35,92 @@ Model output
|
||||
└─ channel send (block replies)
|
||||
```
|
||||
|
||||
Легенда:
|
||||
Позначення:
|
||||
|
||||
- `text_delta/events`: події потоку моделі (можуть бути розрідженими для моделей без streaming).
|
||||
- `chunker`: `EmbeddedBlockChunker`, який застосовує мінімальні/максимальні межі + пріоритет розриву.
|
||||
- `channel send`: фактичні вихідні повідомлення (відповіді блоками).
|
||||
- `text_delta/events`: події потоку моделі (можуть бути рідкісними для моделей без потокової передачі).
|
||||
- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + пріоритет розриву.
|
||||
- `channel send`: фактичні вихідні повідомлення (блокові відповіді).
|
||||
|
||||
**Керування:**
|
||||
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (`"off"` за замовчуванням).
|
||||
- Перевизначення для каналу: `*.blockStreaming` (і варіанти для окремих облікових записів), щоб примусово встановити `"on"`/`"off"` для кожного каналу.
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (типово вимкнено).
|
||||
- Перевизначення каналу: `*.blockStreaming` (і варіанти для окремих акаунтів), щоб примусово встановити `"on"`/`"off"` для кожного каналу.
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` або `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднання потокових блоків перед надсиланням).
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (об’єднання переданих у потоці блоків перед надсиланням).
|
||||
- Жорстке обмеження каналу: `*.textChunkLimit` (наприклад, `channels.whatsapp.textChunkLimit`).
|
||||
- Режим розбиття каналу: `*.chunkMode` (`length` за замовчуванням, `newline` розбиває за порожніми рядками (межами абзаців) перед розбиттям за довжиною).
|
||||
- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (`17` за замовчуванням) розбиває високі відповіді, щоб уникнути обрізання в UI.
|
||||
- Режим розбиття каналу: `*.chunkMode` (`length` типово, `newline` розбиває за порожніми рядками (межі абзаців) перед розбиттям за довжиною).
|
||||
- М’яке обмеження Discord: `channels.discord.maxLinesPerMessage` (типово 17) розбиває високі відповіді, щоб уникнути обрізання в UI.
|
||||
|
||||
**Семантика меж:**
|
||||
|
||||
- `text_end`: передавати блоки, щойно chunker їх видає; скидати на кожному `text_end`.
|
||||
- `message_end`: чекати, доки завершиться повідомлення помічника, а потім скидати буферизований вміст.
|
||||
- `text_end`: передавати блоки, щойно їх надсилає chunker; скидати на кожному `text_end`.
|
||||
- `message_end`: чекати, доки повідомлення помічника завершиться, а потім скинути буферизований вивід.
|
||||
|
||||
`message_end` усе одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому наприкінці він може видати кілька фрагментів.
|
||||
`message_end` все одно використовує chunker, якщо буферизований текст перевищує `maxChars`, тому в кінці він може надсилати кілька фрагментів.
|
||||
|
||||
### Доставка медіа з block streaming
|
||||
### Доставка медіа з блоковою потоковою передачею
|
||||
|
||||
Директиви `MEDIA:` — це звичайні метадані доставки. Коли block streaming
|
||||
рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне корисне навантаження помічника повторює ту саму URL-адресу медіа, фінальна доставка прибирає дублікат медіа замість повторного надсилання вкладення.
|
||||
Директиви `MEDIA:` — це звичайні метадані доставки. Коли блокова потокова передача рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальний payload помічника повторює ту саму URL-адресу медіа, фінальна доставка прибирає дубльоване медіа замість повторного надсилання вкладення.
|
||||
|
||||
Точні дублікати фінального payload пригнічуються. Якщо фінальний payload додає
|
||||
відмінний текст навколо медіа, яке вже було передано потоком, OpenClaw все одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових повідомлень або файлів у таких каналах, як Telegram, коли агент надсилає `MEDIA:` під час streaming, а провайдер також включає його до завершеної відповіді.
|
||||
Точні дублікати фінального payload не надсилаються. Якщо фінальний payload додає окремий текст навколо медіа, яке вже було передано в потоці, OpenClaw усе одно надсилає новий текст, зберігаючи одноразову доставку медіа. Це запобігає дублюванню голосових повідомлень або файлів у таких каналах, як Telegram, коли агент надсилає `MEDIA:` під час потокової передачі, а провайдер також включає його в завершену відповідь.
|
||||
|
||||
## Алгоритм chunking (нижня/верхня межі)
|
||||
## Алгоритм розбиття на фрагменти (нижня/верхня межі)
|
||||
|
||||
Block chunking реалізовано в `EmbeddedBlockChunker`:
|
||||
Розбиття блоків реалізовано в `EmbeddedBlockChunker`:
|
||||
|
||||
- **Нижня межа:** не видавати, доки буфер < `minChars` (якщо не примусово).
|
||||
- **Верхня межа:** намагатися розбивати до `maxChars`; якщо примусово, розбивати на `maxChars`.
|
||||
- **Нижня межа:** не надсилати, доки буфер не досягне `minChars` (якщо не примусово).
|
||||
- **Верхня межа:** намагатися розбити до `maxChars`; якщо примусово, розбивати на `maxChars`.
|
||||
- **Пріоритет розриву:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив.
|
||||
- **Code fences:** ніколи не розбивати всередині fences; коли примусово на `maxChars`, закривати й знову відкривати fence, щоб Markdown залишався коректним.
|
||||
- **Огорожі коду:** ніколи не розбивати всередині них; у разі примусового розбиття на `maxChars` закривати й знову відкривати огорожу, щоб Markdown залишався коректним.
|
||||
|
||||
`maxChars` обмежується значенням канального `textChunkLimit`, тому перевищити ліміти для конкретного каналу не можна.
|
||||
`maxChars` обмежується значенням `textChunkLimit` каналу, тому перевищити ліміти конкретного каналу неможливо.
|
||||
|
||||
## Coalescing (об’єднання потокових блоків)
|
||||
## Об’єднання (злиття блоків із потоку)
|
||||
|
||||
Коли block streaming увімкнено, OpenClaw може **об’єднувати послідовні block chunks**
|
||||
перед їх надсиланням. Це зменшує “спам із одного рядка”, але при цьому зберігає
|
||||
поступове виведення.
|
||||
Коли блокову потокову передачу увімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їх надсиланням. Це зменшує «спам одним рядком», але водночас забезпечує поступову доставку виводу.
|
||||
|
||||
- Coalescing чекає на **паузи без активності** (`idleMs`) перед скиданням.
|
||||
- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать його.
|
||||
- `minChars` не дає надсилати надто малі фрагменти, доки не накопичиться достатньо тексту
|
||||
(фінальне скидання завжди надсилає залишковий текст).
|
||||
- Роздільник визначається з `blockStreamingChunk.breakPreference`
|
||||
- Об’єднання чекає **пауз без активності** (`idleMs`) перед скиданням.
|
||||
- Буфери обмежені `maxChars` і будуть скинуті, якщо перевищать це значення.
|
||||
- `minChars` не дає надсилати надто малі фрагменти, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишковий текст).
|
||||
- Розділювач визначається з `blockStreamingChunk.breakPreference`
|
||||
(`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл).
|
||||
- Перевизначення для каналу доступні через `*.blockStreamingCoalesce` (зокрема в конфігураціях окремих облікових записів).
|
||||
- Значення coalesce `minChars` за замовчуванням підвищується до `1500` для Signal/Slack/Discord, якщо не перевизначено.
|
||||
- Доступні перевизначення на рівні каналу через `*.blockStreamingCoalesce` (зокрема конфігурації для окремих акаунтів).
|
||||
- Типове значення coalesce `minChars` підвищується до 1500 для Signal/Slack/Discord, якщо не перевизначено.
|
||||
|
||||
## Людиноподібна пауза між блоками
|
||||
## Людиноподібний ритм між блоками
|
||||
|
||||
Коли block streaming увімкнено, можна додати **випадкову паузу** між
|
||||
відповідями блоками (після першого блоку). Це робить відповіді з кількох бульбашок природнішими.
|
||||
Коли блокову потокову передачу увімкнено, можна додати **випадкову паузу** між блоковими відповідями (після першого блока). Це робить багатобульбашкові відповіді природнішими.
|
||||
|
||||
- Конфігурація: `agents.defaults.humanDelay` (можна перевизначити для агента через `agents.list[].humanDelay`).
|
||||
- Режими: `off` (за замовчуванням), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).
|
||||
- Застосовується лише до **відповідей блоками**, а не до фінальних відповідей чи підсумків інструментів.
|
||||
- Режими: `off` (типово), `natural` (800–2500 мс), `custom` (`minMs`/`maxMs`).
|
||||
- Застосовується лише до **блокових відповідей**, а не до фінальних відповідей або підсумків інструментів.
|
||||
|
||||
## "Stream chunks or everything"
|
||||
## «Передавати фрагменти чи все»
|
||||
|
||||
Це зіставляється так:
|
||||
Це відповідає таким налаштуванням:
|
||||
|
||||
- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (видавати в процесі). Для каналів, окрім Telegram, також потрібно `*.blockStreaming: true`.
|
||||
- **Stream everything at end:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо, кількома фрагментами, якщо відповідь дуже довга).
|
||||
- **No block streaming:** `blockStreamingDefault: "off"` (лише фінальна відповідь).
|
||||
- **Передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (надсилати в міру готовності). Для каналів, відмінних від Telegram, також потрібно `*.blockStreaming: true`.
|
||||
- **Передати все наприкінці:** `blockStreamingBreak: "message_end"` (одне скидання, можливо з кількома фрагментами, якщо текст дуже довгий).
|
||||
- **Без блокової потокової передачі:** `blockStreamingDefault: "off"` (лише фінальна відповідь).
|
||||
|
||||
**Примітка щодо каналів:** Block streaming **вимкнено, доки**
|
||||
`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий preview
|
||||
(`channels.<channel>.streaming`) без відповідей блоками.
|
||||
**Примітка щодо каналів:** Блокова потокова передача **вимкнена, якщо тільки**
|
||||
`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд (`channels.<channel>.streaming`) без блокових відповідей.
|
||||
|
||||
Нагадування про розташування конфігурації: значення за замовчуванням `blockStreaming*` знаходяться в `agents.defaults`, а не в корені конфігурації.
|
||||
Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в корені конфігурації.
|
||||
|
||||
## Режими preview streaming
|
||||
## Режими потокової передачі попереднього перегляду
|
||||
|
||||
Канонічний ключ: `channels.<channel>.streaming`
|
||||
|
||||
Режими:
|
||||
|
||||
- `off`: вимкнути preview streaming.
|
||||
- `partial`: один preview, який замінюється найсвіжішим текстом.
|
||||
- `block`: preview оновлюється chunked/appended-кроками.
|
||||
- `progress`: preview прогресу/статусу під час генерації, фінальна відповідь після завершення.
|
||||
- `off`: вимкнути потокову передачу попереднього перегляду.
|
||||
- `partial`: один попередній перегляд, який замінюється найновішим текстом.
|
||||
- `block`: оновлення попереднього перегляду поетапними фрагментами/додаваннями.
|
||||
- `progress`: попередній перегляд статусу/прогресу під час генерації, фінальна відповідь після завершення.
|
||||
|
||||
### Зіставлення каналів
|
||||
### Відповідність каналів
|
||||
|
||||
| Канал | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------- |
|
||||
@ -138,60 +131,61 @@ Block chunking реалізовано в `EmbeddedBlockChunker`:
|
||||
|
||||
Лише для Slack:
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` перемикає виклики нативного Slack streaming API, коли `channels.slack.streaming.mode="partial"` (`true` за замовчуванням).
|
||||
- Нативний Slack streaming і статус потоку помічника в Slack thread вимагають цільового потоку відповіді; DM верхнього рівня не показують такий preview у стилі thread.
|
||||
- `channels.slack.streaming.nativeTransport` вмикає/вимикає власні виклики API потокової передачі Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`).
|
||||
- Власна потокова передача Slack і статус потоку помічника Slack вимагають ціль відповіді у гілці; DM верхнього рівня не показують такий попередній перегляд у стилі гілки.
|
||||
|
||||
Міграція застарілих ключів:
|
||||
|
||||
- Telegram: застарілі `streamMode` і скалярні/булеві значення `streaming` виявляються та мігруються шляхами doctor/config compatibility до `streaming.mode`.
|
||||
- Discord: `streamMode` + булеве `streaming` автоматично мігрують до enum `streaming`.
|
||||
- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булеве `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`.
|
||||
- Telegram: застарілі `streamMode` і скалярні/булеві значення `streaming` виявляються й переносяться шляхами doctor/config compatibility до `streaming.mode`.
|
||||
- Discord: `streamMode` + булевий `streaming` автоматично переносяться до enum `streaming`.
|
||||
- Slack: `streamMode` автоматично переноситься до `streaming.mode`; булевий `streaming` автоматично переноситься до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично переноситься до `streaming.nativeTransport`.
|
||||
|
||||
### Поведінка під час виконання
|
||||
|
||||
Telegram:
|
||||
|
||||
- Використовує `sendMessage` + `editMessageText` для оновлень preview у DM, групах і темах.
|
||||
- Preview streaming пропускається, якщо для Telegram явно увімкнено block streaming (щоб уникнути подвійного streaming).
|
||||
- `/reasoning stream` може записувати reasoning у preview.
|
||||
- Використовує оновлення попереднього перегляду через `sendMessage` + `editMessageText` у DM і групах/темах.
|
||||
- Надсилає нове фінальне повідомлення замість редагування на місці, якщо попередній перегляд був видимий приблизно одну хвилину, а потім прибирає його, щоб мітка часу Telegram відображала завершення відповіді.
|
||||
- Потокова передача попереднього перегляду пропускається, якщо блокову потокову передачу Telegram явно ввімкнено (щоб уникнути подвійної потокової передачі).
|
||||
- `/reasoning stream` може записувати міркування до попереднього перегляду.
|
||||
|
||||
Discord:
|
||||
|
||||
- Використовує надсилання + редагування preview-повідомлень.
|
||||
- Режим `block` використовує чернетковий chunking (`draftChunk`).
|
||||
- Preview streaming пропускається, якщо для Discord явно увімкнено block streaming.
|
||||
- Фінальні payload для медіа, помилок і explicit reply скасовують очікувані preview без скидання нової чернетки, а потім використовують звичайну доставку.
|
||||
- Використовує надсилання + редагування повідомлень попереднього перегляду.
|
||||
- Режим `block` використовує чернеткове розбиття (`draftChunk`).
|
||||
- Потокова передача попереднього перегляду пропускається, якщо блокову потокову передачу Discord явно ввімкнено.
|
||||
- Фінальні payload для медіа, помилок і явних відповідей скасовують очікувані попередні перегляди без скидання нової чернетки, а потім використовують звичайну доставку.
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` може використовувати нативний Slack streaming (`chat.startStream`/`append`/`stop`), якщо доступний.
|
||||
- `block` використовує preview чернеток у стилі append.
|
||||
- `progress` використовує текст preview статусу, а потім фінальну відповідь.
|
||||
- Нативний і чернетковий preview streaming пригнічують block replies для цього ходу, тому відповідь Slack передається лише одним шляхом доставки.
|
||||
- Фінальні payload для медіа/помилок і фінали progress не створюють тимчасових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати preview, скидають очікуваний текст чернетки.
|
||||
- `partial` може використовувати власну потокову передачу Slack (`chat.startStream`/`append`/`stop`), якщо вона доступна.
|
||||
- `block` використовує попередні перегляди чернеток у стилі додавання.
|
||||
- `progress` використовує текст попереднього перегляду статусу, а потім фінальну відповідь.
|
||||
- Власна та чернеткова потокова передача попереднього перегляду пригнічують блокові відповіді для цього ходу, тож відповідь Slack передається лише одним шляхом доставки.
|
||||
- Фінальні payload для медіа/помилок і фінали progress не створюють тимчасових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний текст чернетки.
|
||||
|
||||
Mattermost:
|
||||
|
||||
- Передає thinking, активність інструментів і частковий текст відповіді в один чернетковий preview post, який фіналізується на місці, коли фінальну відповідь уже безпечно надсилати.
|
||||
- Повертається до надсилання нового фінального post, якщо preview post було видалено або він інакше недоступний на момент фіналізації.
|
||||
- Фінальні payload для медіа/помилок скасовують очікувані оновлення preview перед звичайною доставкою замість скидання тимчасового preview post.
|
||||
- Передає міркування, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь можна безпечно надіслати.
|
||||
- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний у момент фіналізації.
|
||||
- Фінальні payload для медіа/помилок скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасового допису попереднього перегляду.
|
||||
|
||||
Matrix:
|
||||
|
||||
- Чернеткові preview фіналізуються на місці, коли фінальний текст може повторно використати подію preview.
|
||||
- Фінали лише з медіа, з помилками та з невідповідністю цілі reply скасовують очікувані оновлення preview перед звичайною доставкою; уже видимий застарілий preview редагується.
|
||||
- Чернеткові попередні перегляди фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду.
|
||||
- Фінали лише з медіа, з помилками і з невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується.
|
||||
|
||||
### Оновлення preview із прогресом інструментів
|
||||
### Оновлення попереднього перегляду прогресу інструментів
|
||||
|
||||
Preview streaming також може включати оновлення **tool-progress** — короткі рядки статусу на кшталт "searching the web", "reading file" або "calling tool", — які з’являються в тому самому preview-повідомленні під час роботи інструментів, до фінальної відповіді. Це робить багатокрокові ходи з інструментами візуально активними, а не мовчазними між першим preview мислення і фінальною відповіддю.
|
||||
Потокова передача попереднього перегляду також може включати оновлення **прогресу інструментів** — короткі рядки стану на кшталт «пошук у вебі», «читання файла» або «виклик інструмента», які з’являються в тому самому повідомленні попереднього перегляду під час роботи інструментів, ще до фінальної відповіді. Це робить багатоетапні ходи з інструментами візуально активними, а не мовчазними між першим попереднім переглядом міркувань і фінальною відповіддю.
|
||||
|
||||
Підтримувані поверхні:
|
||||
|
||||
- **Discord**, **Slack** і **Telegram** за замовчуванням передають tool-progress у live preview edit, коли preview streaming активний.
|
||||
- Для Telegram оновлення preview з tool-progress постачаються увімкненими з `v2026.4.22`; збереження їх увімкненими підтримує вже випущену поведінку.
|
||||
- **Mattermost** уже включає активність інструментів у свій один чернетковий preview post (див. вище).
|
||||
- Редагування tool-progress наслідують активний режим preview streaming; вони пропускаються, коли preview streaming має значення `off` або коли block streaming уже взяв повідомлення під контроль.
|
||||
- Щоб зберегти preview streaming, але приховати рядки tool-progress, установіть `streaming.preview.toolProgress` в `false` для цього каналу. Щоб повністю вимкнути редагування preview, установіть `streaming.mode` в `off`.
|
||||
- **Discord**, **Slack** і **Telegram** типово передають прогрес інструментів у живе редагування попереднього перегляду, коли потокову передачу попереднього перегляду активовано.
|
||||
- Для Telegram оновлення попереднього перегляду прогресу інструментів увімкнено в релізі, починаючи з `v2026.4.22`; збереження цього стану підтримує вже випущену поведінку.
|
||||
- **Mattermost** уже включає активність інструментів у свій єдиний чернетковий допис попереднього перегляду (див. вище).
|
||||
- Редагування прогресу інструментів дотримуються активного режиму потокової передачі попереднього перегляду; вони пропускаються, коли потокову передачу попереднього перегляду вимкнено (`off`) або коли керування повідомленням перебрала блокова потокова передача.
|
||||
- Щоб зберегти потокову передачу попереднього перегляду, але приховати рядки прогресу інструментів, установіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, установіть `streaming.mode` у `off`.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -212,6 +206,6 @@ Preview streaming також може включати оновлення **tool
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлення й доставка
|
||||
- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлення та доставка
|
||||
- [Повторні спроби](/uk/concepts/retry) — поведінка повторних спроб у разі збою доставки
|
||||
- [Канали](/uk/channels) — підтримка streaming для кожного каналу
|
||||
- [Канали](/uk/channels) — підтримка потокової передачі для окремих каналів
|
||||
|
||||
Loading…
Reference in New Issue
Block a user