diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index eb06ad2b8..10da3150b 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,28 +1,28 @@ --- read_when: - - Робота над функціями Telegram або Webhook -summary: Стан підтримки, можливості та конфігурація бота Telegram + - Робота з функціями Telegram або Webhook +summary: Стан підтримки, можливості та налаштування бота Telegram title: Telegram x-i18n: - generated_at: "2026-04-30T12:42:32Z" + generated_at: "2026-04-30T15:20:22Z" model: gpt-5.5 provider: openai - source_hash: 5df2a27a801183b2817beca228c41c04f855ef08720f6c7505b49eae22ea303d + source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd source_path: channels/telegram.md workflow: 16 --- -Готово до production для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим webhook необов’язковий. +Готово до production для DM ботів і груп через grammY. Довге опитування є стандартним режимом; режим Webhook необов’язковий. Типова політика DM для Telegram — сполучення. - - Діагностика між каналами та сценарії ремонту. + + Міжканальна діагностика й інструкції з відновлення. - Повні шаблони й приклади конфігурації каналів. + Повні шаблони та приклади конфігурації каналів. @@ -30,7 +30,7 @@ x-i18n: - Відкрийте Telegram і напишіть **@BotFather** (переконайтеся, що handle саме `@BotFather`). + Відкрийте Telegram і напишіть **@BotFather** (переконайтеся, що handle точно `@BotFather`). Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. @@ -51,7 +51,7 @@ x-i18n: } ``` - Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис). Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. @@ -74,16 +74,16 @@ openclaw pairing approve telegram -Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису. -## Налаштування на стороні Telegram +## Налаштування на боці Telegram - Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. + Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі групові повідомлення, зробіть одне з двох: + Якщо бот має бачити всі групові повідомлення, зробіть одне з такого: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. @@ -95,44 +95,44 @@ openclaw pairing approve telegram Статус адміністратора керується в налаштуваннях групи Telegram. - Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. + Боти-адміністратори отримують усі групові повідомлення, що корисно для постійної поведінки в групі. - - `/setjoingroups`, щоб дозволити або заборонити додавання до груп + - `/setjoingroups` для дозволу/заборони додавання до груп - `/setprivacy` для поведінки видимості в групах -## Контроль доступу й активація +## Контроль доступу та активація `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - `pairing` (за замовчуванням) - - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) - - `open` (потрібно, щоб `allowFrom` містив `"*"`) + - `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 і відхиляється валідацією конфігурації. + `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 `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токен бота Telegram). Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `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:`. + Поширена плутанина: схвалення сполучення DM не означає "цей відправник авторизований всюди". + Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. + Авторизація відправників у групах усе ще надходить із явних allowlist у конфігурації. + Якщо ви хочете "я авторизований один раз, і працюють і DM, і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram @@ -156,25 +156,25 @@ curl "https://api.telegram.org/bot/getUpdates" Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - - немає config `groups`: + - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) + - `groups` налаштовано: діє як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (за замовчуванням) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групі. Якщо не задано, Telegram повертається до `allowFrom`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram використовує резервний `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID груп або супергруп Telegram у `groupAllowFrom`. Від’ємні chat ID належать до `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): автентифікація відправника в групі **не** успадковує схвалення зі сховища сполучень DM. - Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. + Нечислові записи ігноруються для авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень DM. + Сполучення лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для конкретної групи/теми. + Якщо `groupAllowFrom` не задано, Telegram використовує резервний config `allowFrom`, а не сховище сполучень. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретних користувачів в одній конкретній групі: + Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи: ```json5 { @@ -213,16 +213,16 @@ curl "https://api.telegram.org/bot/getUpdates" Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. - - Додавайте від’ємні ID груп або супергруп Telegram, наприклад `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, наприклад `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди в дозволеній групі можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. + - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. - Відповіді в групі за замовчуванням потребують згадки. + Групові відповіді за замовчуванням потребують згадки. Згадка може надходити з: @@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для постійності використовуйте конфігурацію. + Вони оновлюють лише стан сесії. Використовуйте конфігурацію для постійності. Приклад постійної конфігурації: @@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Отримання chat ID групи: + Отримання ID групового чату: - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` - або прочитайте `chat.id` з `openclaw logs --follow` @@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали). +- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали). - Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб тримати теми ізольованими. -- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесій і зберігає ID треду для відповідей. -- Long polling використовує runner grammY з послідовністю на рівні чату/треду. Загальна concurrency sink runner використовує `agents.defaults.maxConcurrent`. -- Long polling захищений усередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший gateway OpenClaw, скрипт або зовнішній poller, імовірно, використовує той самий токен. -- Перезапуски watchdog для long-polling за замовчуванням запускаються після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні polling-stall перезапуски під час довготривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються override на рівні облікового запису. -- Telegram Bot API не підтримує read-receipt (`sendReadReceipts` не застосовується). +- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб ізолювати теми. +- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей. +- Довге опитування використовує grammY runner із послідовністю на рівні чату/thread. Загальна concurrency sink у runner використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший OpenClaw gateway, script або зовнішній poller використовує той самий токен. +- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для кожного облікового запису. +- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - - прямі чати: preview-повідомлення + `editMessageText` - - групи/теми: preview-повідомлення + `editMessageText` + - прямі чати: повідомлення попереднього перегляду + `editMessageText` + - групи/теми: повідомлення попереднього перегляду + `editMessageText` Вимога: - - `channels.telegram.streaming` дорівнює `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` відображається на `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане preview-повідомлення (за замовчуванням: `true`, коли preview streaming активний) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` + - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) + - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли streaming попереднього перегляду активний) + - застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` - Preview-оновлення прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти відредагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Працюю...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніших версій. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,16 +306,16 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку тільки фінальної відповіді: preview-редагування Telegram вимикаються, а загальний шум інструментів/прогресу приглушується замість надсилання окремими повідомленнями "Working...". Запити на схвалення, медіа payload і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете залишити лише preview-редагування відповіді, приховавши статусні рядки прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення "Працюю...". Запити на схвалення, медіа payloads і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. - Для відповідей лише текстом: + Для відповідей лише з текстом: - - короткі попередні перегляди DM/групи/теми: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці - - попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіанавантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Потік міркувань лише для Telegram: @@ -324,25 +324,25 @@ curl "https://api.telegram.org/bot/getUpdates" - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст. + - Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram. + - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. - + Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Типові значення вбудованих команд: + Типові значення власних команд: - - `commands.native: "auto"` вмикає вбудовані команди для Telegram + - `commands.native: "auto"` вмикає власні команди для Telegram - Додайте користувацькі записи меню команд: + Додайте власні записи меню команд: ```json5 { @@ -359,47 +359,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - назви нормалізуються (початковий `/` видаляється, усе переводиться в нижній регістр) + - імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - користувацькі команди не можуть перевизначати вбудовані команди + - власні команди не можуть перевизначати вбудовані команди - конфлікти/дублікати пропускаються й записуються в журнал Примітки: - - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - - команди Plugin/Skills усе ще можуть працювати під час введення, навіть якщо не показані в меню Telegram + - власні команди є лише записами меню; вони не реалізують поведінку автоматично + - команди plugin/skill можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо вбудовані команди вимкнено, вбудовані елементи видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано. + Якщо власні команди вимкнено, вбудовані видаляються. Користувацькі команди або команди Plugin можуть і далі реєструватися, якщо це налаштовано. - Типові помилки налаштування: + Поширені помилки налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тож це не повідомляється як помилка очищення Webhook. - - `setMyCommands failed` з помилками мережі/отримання зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`. + - помилки `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, можуть означати, що `channels.telegram.apiRoot` було встановлено як повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - `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` встановлено: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список запитів, що очікують (включно з роллю/областями) + 3. `/pair pending` перелічує запити, що очікують (включно з роллю/областями) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один запит, що очікує - `/pair approve latest` для найновішого - Код налаштування містить короткочасний початковий токен. Вбудована передача початкових даних зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки початкової області мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; неоператорські ролі все ще потребують областей із власним префіксом ролі. + Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного Node на `scopes: []`; будь-який переданий токен оператора лишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролі, що не є операторськими, усе ще потребують областей під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роллю/областями/публічним ключем), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. + Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області/публічний ключ), попередній запит, що очікував, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - - Налаштуйте область вбудованої клавіатури: + + Налаштуйте область inline-клавіатури: ```json5 { @@ -439,7 +439,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. Приклад дії повідомлення: @@ -459,23 +459,23 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Натискання зворотного виклику передаються агенту як текст: + Натискання callback передаються агенту як текст: `callback_data: ` - + Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`) Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Елементи керування допуском: + Елементи керування обмеженнями: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -483,17 +483,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціальне повторне розв’язання SecretRef для кожного надсилання. + Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - + Telegram підтримує явні теги гілкування відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що запустило дію - - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram + - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск + - `[[reply_to:]]` відповідає на певний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -501,27 +501,27 @@ curl "https://api.telegram.org/bot/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_*]]` усе ще враховуються. - - Супергрупи форуму: + + Форумні супергрупи: - ключі сесій тем додають `:topic:` - - відповіді та індикатор введення спрямовуються в гілку теми + - відповіді та індикатор набору тексту спрямовуються в гілку теми - шлях конфігурації теми: `channels.telegram.groups..topics.` - Спеціальний випадок загальної теми (`threadId=1`): + Особливий випадок загальної теми (`threadId=1`): - - надсилання повідомлень опускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії введення все ще включають `message_thread_id` + - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії набору тексту все одно включають `message_thread_id` - Успадкування теми: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` застосовується лише до теми й не успадковується з типових значень групи. + Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` є лише для теми й не успадковується з типових значень групи. **Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: @@ -543,25 +543,25 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування теми ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з уточненням теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та кваліфікованим за темою id на кшталт `-1001234567890:topic:42`). Наразі обмежено форумними темами в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Запуск ACP із чату, прив’язаний до гілки**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Прив’язаний до гілки запуск ACP з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок. + Контекст шаблону відкриває `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок. - + ### Аудіоповідомлення Telegram розрізняє голосові нотатки та аудіофайли. - - за замовчуванням: поведінка аудіофайлу + - за замовчуванням: поведінка аудіофайла - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку - - вхідні транскрипти голосових нотаток оформлюються як машинно згенерований, - недовірений текст у контексті агента; виявлення згадки все ще використовує сирий + - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, + ненадійний текст у контексті агента; виявлення згадок усе ще використовує сирий транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. Приклад дії повідомлення: @@ -598,7 +598,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується та обробляється (заповнювач ``) + - статичний WEBP: завантажується й обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -614,9 +614,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити повторні виклики зору. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision. - Увімкнути дії зі стікерами: + Увімкніть дії зі стікерами: ```json5 { @@ -654,7 +654,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Реакції Telegram надходять як оновлення `message_reaction` (окремо від навантажень повідомлень). Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: @@ -669,28 +669,28 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). - - Події реакцій усе одно враховують засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - Telegram не надає ідентифікатори тем у оновленнях реакцій. - нефорумні групи маршрутизуються до сесії групового чату - форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для polling/webhook автоматично включає `message_reaction`. + `allowed_updates` для polling/Webhook автоматично включає `message_reaction`. `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок вирішення: + Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - запасний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode-емодзі (наприклад "👀"). + - Telegram очікує емодзі Unicode (наприклад "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. @@ -700,8 +700,8 @@ curl "https://api.telegram.org/bot/getUpdates" Записи, ініційовані Telegram, включають: - - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потрібне ввімкнення команд) + - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` + - `/config set` і `/config unset` (потребує ввімкнення команд) Вимкнення: @@ -717,31 +717,31 @@ curl "https://api.telegram.org/bot/getUpdates" - - За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типово `/telegram-webhook`, `127.0.0.1`, `8787`). + + За замовчуванням використовується довге опитування. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі окремі для кожного чату/теми лінії бота, що й long polling, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим Webhook перевіряє захист запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі доріжки бота для кожного чату/теми, що й довге опитування, тому повільні ходи агента не затримують ACK доставки Telegram. - + - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `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.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів із довгим опитуванням обмежують налаштовані значення нижче 45-секундного захисту запиту `getUpdates`, щоб бездіяльні опитування не переривалися до завершення 30-секундного вікна опитування. + - Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування. - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. - - додатковий контекст reply/quote/forward наразі передається як отриманий. - - allowlist Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - додатковий контекст відповіді/цитати/пересилання наразі передається як отримано. + - списки дозволених Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до помічників надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної відповіді для вхідних повідомлень також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram перед підключенням, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка остаточної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram перед підключенням, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення. - Ціль надсилання CLI може бути числовим ID чату або іменем користувача: + Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" @@ -767,32 +767,32 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для inline-клавіатур, коли це дозволяє `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.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими - Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram. + Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ідентифікаторами користувачів Telegram. Шлях конфігурації: - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача) - - `channels.telegram.execApprovals.approvers` (повертається до числових ID власників із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.approvers` (повертається до числових ідентифікаторів власників із `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`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ідентифікаторів у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення й подальшого повідомлення. Схвалення exec типово спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Термін дії схвалень exec за замовчуванням спливає через 30 хвилин. - Inline-кнопки схвалення також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалення з префіксом `plugin:` вирішуються через схвалення plugin; інші спершу вирішуються через схвалення exec. + Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Ідентифікатори схвалення з префіксом `plugin:` визначаються через схвалення Plugin; інші спершу визначаються через схвалення exec. Див. [Схвалення exec](/uk/tools/exec-approvals). @@ -801,14 +801,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або приховати її. Цією поведінкою керують два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації: -| Ключ | Значення | Типово | Опис | -| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------- | +| Ключ | Значення | Типово | Опис | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приховує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилок під час збоїв. | +| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram). +Підтримуються перевизначення для облікового запису, групи й теми (таке саме успадкування, як і для інших ключів конфігурації Telegram). ```json5 { @@ -835,48 +835,49 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - BotFather: `/setprivacy` -> Disable - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на membership. + - `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство. - швидкий тест сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути в списку (або включати `"*"`) - - перевірте membership бота в групі + - коли існує `channels.telegram.groups`, група має бути перелічена (або містити `"*"`) + - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте ідентичність відправника (pairing та/або числовий `allowFrom`) + - авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`) - авторизація команд усе одно застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд plugin/skill/custom або вимкніть нативні меню - - стартові виклики `deleteMyCommands` / `setMyCommands` обмежені й повторюються один раз через транспортний fallback Telegram у разі timeout запиту. Постійні помилки network/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню + - стартові виклики `deleteMyCommands` / `setMyCommands` обмежені та повторюються один раз через транспортний fallback Telegram у разі тайм-ауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого bot token. - - Повторно скопіюйте або згенеруйте bot token у BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. - - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування її як "no webhook exists" лише відклало б той самий збій через поганий токен до подальших API-викликів. - - Якщо `deleteWebhook` завершується з transient network error під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній webhook URL, polling продовжується, бо cleanup уже задоволено. + - `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота. + - Повторно скопіюйте або згенеруйте токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. + - `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "Webhook не існує" лише відклало б той самий збій через неправильний токен до пізніших викликів API. + - Якщо `deleteWebhook` завершується помилкою через тимчасову мережеву помилку під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL Webhook, polling продовжується, бо очищення вже задоволене. - - Node 22+ + власний fetch/proxy може спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються. - - Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний IPv6 egress може спричиняти періодичні збої 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, коли активний обліковий запис webhook не завершив `setWebhook` після startup grace або коли остання успішна активність транспорту polling застаріла. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` здорові, але ваш хост усе одно повідомляє хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`. - - Telegram також враховує env proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для service environment і стандартного env proxy немає, Telegram також використовує цю URL-адресу для транспорту Bot API. - - На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. + - Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний IPv6 egress може спричиняти періодичні збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки. + - Якщо сокети Telegram повторно створюються з коротким фіксованим інтервалом, перевірте, чи не встановлено мале значення `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче за запобіжник запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. + - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений акаунт polling не завершив `getUpdates` після початкового пільгового періоду, коли запущений акаунт webhook не завершив `setWebhook` після початкового пільгового періоду або коли остання успішна активність транспорту polling застаріла. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`. + - Telegram також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартні змінні середовища proxy відсутні, Telegram також використовує цю URL-адресу для транспорту Bot API. + - На VPS-хостах із нестабільним прямим egress/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -884,8 +885,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ за замовчуванням має `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост — WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (окрім WSL2) і `dnsResultOrder=ipv4first`. + - Якщо ваш хост — WSL2 або явно краще працює в режимі лише IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -894,11 +895,11 @@ 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: + прозорий proxy переписує `api.telegram.org` на іншу + приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете + увімкнути обхід лише для Telegram: ```yaml channels: @@ -907,26 +908,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Та сама явна згода доступна для кожного облікового запису за адресою + - Та сама opt-in опція доступна для кожного акаунта за адресою `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш проксі перетворює хости медіа Telegram на `198.18.x.x`, спершу залиште - небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяє - діапазон еталонного тестування RFC 2544. + - Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяють benchmark-діапазон RFC 2544 + за замовчуванням. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист - медіа Telegram від SSRF. Використовуйте це лише в довірених проксі-середовищах, - контрольованих оператором, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, - коли вони синтезують приватні або спеціального призначення відповіді поза - діапазоном еталонного тестування RFC 2544. Залиште це вимкненим для звичайного - доступу до Telegram через публічний інтернет. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram + медіа від SSRF. Використовуйте це лише для довірених, контрольованих оператором середовищ proxy, + як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціального використання відповіді поза benchmark-діапазоном RFC 2544. + Залишайте вимкненим для звичайного публічного інтернет-доступу Telegram. - - Перевизначення через змінні середовища (тимчасові): + - Перевизначення середовища (тимчасові): - `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,23 +936,23 @@ dig +short api.telegram.org AAAA -Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting). +Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + -- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) -- підтвердження виконання: `execApprovals`, `accounts.*.execApprovals` +- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlinks відхиляються) +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) +- схвалення exec: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` -- треди/відповіді: `replyToMode` +- потоки/відповіді: `replyToMode` - потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` @@ -962,7 +962,7 @@ dig +short api.telegram.org AAAA -Пріоритет кількох облікових записів: коли налаштовано два або більше 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.*`. ## Пов’язане @@ -972,10 +972,10 @@ dig +short api.telegram.org AAAA Сполучіть користувача Telegram із Gateway. - Поведінка списку дозволених груп і тем. + Поведінка allowlist для груп і тем. - Маршрутизуйте вхідні повідомлення до агентів. + Спрямовуйте вхідні повідомлення до агентів. Модель загроз і посилення захисту. diff --git a/docs/uk/concepts/messages.md b/docs/uk/concepts/messages.md index 87bc9fa58..54497156c 100644 --- a/docs/uk/concepts/messages.md +++ b/docs/uk/concepts/messages.md @@ -1,22 +1,22 @@ --- read_when: - - Пояснення, як вхідні повідомлення перетворюються на відповіді + - Пояснення того, як вхідні повідомлення стають відповідями - Уточнення сеансів, режимів постановки в чергу або поведінки потокового передавання - - Документування видимості міркувань і наслідків використання + - Документування видимості міркувань і наслідків для використання summary: Потік повідомлень, сеанси, постановка в чергу та видимість міркувань title: Повідомлення x-i18n: - generated_at: "2026-04-30T00:29:52Z" + generated_at: "2026-04-30T15:20:32Z" model: gpt-5.5 provider: openai - source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e + source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 source_path: concepts/messages.md workflow: 16 --- -OpenClaw обробляє вхідні повідомлення через конвеєр визначення сесії, постановки в чергу, потокового передавання, виконання інструментів і видимості міркувань. Ця сторінка показує шлях від вхідного повідомлення до відповіді. +OpenClaw обробляє вхідні повідомлення через конвеєр визначення сеансу, постановки в чергу, потокового передавання, виконання інструментів і видимості міркувань. Ця сторінка показує шлях від вхідного повідомлення до відповіді. -## Потік повідомлень (на високому рівні) +## Потік повідомлень (загальний рівень) ``` Inbound message @@ -26,23 +26,23 @@ Inbound message -> outbound replies (channel limits + chunking) ``` -Основні параметри розміщені в конфігурації: +Ключові налаштування містяться в конфігурації: - `messages.*` для префіксів, постановки в чергу та поведінки груп. -- `agents.defaults.*` для типових значень блокового потокового передавання та поділу на фрагменти. +- `agents.defaults.*` для типових значень блокового потокового передавання та розбиття на фрагменти. - Перевизначення каналів (`channels.whatsapp.*`, `channels.telegram.*` тощо) для обмежень і перемикачів потокового передавання. -Повну схему див. у [Конфігурації](/uk/gateway/configuration). +Повну схему див. у [Конфігурація](/uk/gateway/configuration). ## Дедуплікація вхідних повідомлень -Канали можуть повторно доставити те саме повідомлення після повторного підключення. OpenClaw зберігає короткочасний кеш із ключем за каналом/обліковим записом/учасником/сесією/ідентифікатором повідомлення, щоб дубльовані доставки не запускали агента ще раз. +Канали можуть повторно доставляти те саме повідомлення після повторних підключень. OpenClaw зберігає короткоживучий кеш із ключем за каналом/обліковим записом/співрозмовником/сеансом/ідентифікатором повідомлення, щоб дублікати доставок не запускали ще один запуск агента. -## Усунення брязкоту вхідних повідомлень +## Дебаунс вхідних повідомлень -Швидкі послідовні повідомлення від **того самого відправника** можна об’єднати в один хід агента через `messages.inbound`. Усунення брязкоту обмежується каналом + розмовою та використовує найновіше повідомлення для ланцюжків відповідей/ідентифікаторів. +Швидкі послідовні повідомлення від **того самого відправника** можна об’єднати в один хід агента через `messages.inbound`. Дебаунс обмежується окремо для кожного каналу + розмови та використовує найновіше повідомлення для прив’язки відповіді до гілки/ідентифікаторів. -Конфігурація (глобальне типове значення + перевизначення для окремих каналів): +Конфігурація (глобальне типове значення + перевизначення для каналів): ```json5 { @@ -61,78 +61,81 @@ Inbound message Примітки: -- Усунення брязкоту застосовується до повідомлень **лише з текстом**; медіа/вкладення надсилаються негайно. -- Керівні команди обходять усунення брязкоту, щоб залишатися окремими — **крім** випадків, коли канал явно вмикає об’єднання приватних повідомлень від того самого відправника (наприклад, [BlueBubbles `coalesceSameSenderDms`](/uk/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), де команди в приватних повідомленнях очікують у межах вікна усунення брязкоту, щоб розділене під час надсилання корисне навантаження могло долучитися до того самого ходу агента. +- Дебаунс застосовується до **лише текстових** повідомлень; медіа/вкладення скидають буфер негайно. +- Команди керування обходять дебаунс, щоб залишатися окремими, **крім** випадків, коли канал явно вмикає об’єднання DM від того самого відправника (наприклад, [BlueBubbles `coalesceSameSenderDms`](/uk/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), де команди DM очікують у межах вікна дебаунсу, щоб розділене під час надсилання корисне навантаження могло потрапити в той самий хід агента. -## Сесії та пристрої +## Сеанси та пристрої -Сесіями володіє Gateway, а не клієнти. +Сеансами володіє Gateway, а не клієнти. -- Прямі чати згортаються в ключ основної сесії агента. -- Групи/канали отримують власні ключі сесій. -- Сховище сесій і транскрипти розміщені на хості Gateway. +- Прямі чати згортаються в основний ключ сеансу агента. +- Групи/канали отримують власні ключі сеансів. +- Сховище сеансів і транскрипти розміщуються на хості Gateway. -Кілька пристроїв/каналів можуть відповідати тій самій сесії, але історія не повністю синхронізується назад до кожного клієнта. Рекомендація: використовуйте один основний пристрій для довгих розмов, щоб уникнути розбіжності контексту. Control UI та TUI завжди показують транскрипт сесії, підтримуваний Gateway, тож саме вони є джерелом істини. +Кілька пристроїв/каналів можуть зіставлятися з тим самим сеансом, але історія не повністю синхронізується назад до кожного клієнта. Рекомендація: використовуйте один основний пристрій для довгих розмов, щоб уникнути розходження контексту. Control UI і TUI завжди показують транскрипт сеансу, підкріплений Gateway, тому вони є джерелом істини. -Докладніше: [Керування сесіями](/uk/concepts/session). +Докладніше: [Керування сеансами](/uk/concepts/session). -## Метадані результатів інструментів +## Метадані результату інструмента -`content` результату інструмента — це результат, видимий моделі. `details` результату інструмента — це runtime-метадані для відтворення в UI, діагностики, доставки медіа та плагінів. +`content` результату інструмента — це видимий для моделі результат. `details` результату інструмента — це метадані виконання для рендерингу UI, діагностики, доставки медіа та plugins. -OpenClaw явно зберігає цю межу: +OpenClaw зберігає цю межу явною: - `toolResult.details` вилучається перед повторним відтворенням у провайдера та вхідними даними Compaction. -- Збережені транскрипти сесій зберігають лише обмежені `details`; завеликі метадані замінюються компактним підсумком із позначкою `persistedDetailsTruncated: true`. -- Плагіни та інструменти мають розміщувати текст, який модель повинна прочитати, у `content`, а не лише в `details`. +- Збережені транскрипти сеансів містять лише обмежені `details`; завеликі метадані замінюються компактним підсумком із позначкою `persistedDetailsTruncated: true`. +- Plugins та інструменти мають розміщувати текст, який модель повинна прочитати, у `content`, а не лише в `details`. ## Тіла вхідних повідомлень і контекст історії -OpenClaw розділяє **тіло промпта** та **тіло команди**: +OpenClaw розділяє **тіло запиту** та **тіло команди**: -- `Body`: текст промпта, надісланий агенту. Він може містити оболонки каналу й необов’язкові обгортки історії. -- `CommandBody`: сирий текст користувача для розбору директив/команд. +- `BodyForAgent`: основний видимий для моделі текст поточного повідомлення. Plugins каналів мають тримати його зосередженим на поточному тексті відправника, що містить запит. +- `Body`: застарілий резервний варіант запиту. Він може містити оболонки каналу й необов’язкові обгортки історії, але поточні канали не повинні покладатися на нього як на основні вхідні дані моделі, коли доступний `BodyForAgent`. +- `CommandBody`: необроблений текст користувача для розбору директив/команд. - `RawBody`: застарілий псевдонім для `CommandBody` (збережено для сумісності). Коли канал надає історію, він використовує спільну обгортку: -- `[Chat messages since your last reply - for context]` -- `[Current message - respond to this]` +- `[Повідомлення чату з часу вашої останньої відповіді — для контексту]` +- `[Поточне повідомлення — відповідайте на нього]` -Для **непрямих чатів** (груп/каналів/кімнат) **тіло поточного повідомлення** має префікс із міткою відправника (у тому самому стилі, що й записи історії). Це забезпечує узгодженість повідомлень у реальному часі та повідомлень у черзі/історії в промпті агента. +Для **непрямих чатів** (груп/каналів/кімнат) **тіло поточного повідомлення** має префікс із міткою відправника (той самий стиль, що використовується для записів історії). Це зберігає узгодженість повідомлень у реальному часі та повідомлень із черги/історії в запиті агента. -Буфери історії є **лише очікуваними**: вони містять групові повідомлення, які _не_ запускали виконання (наприклад, повідомлення, що потребували згадки), і **не містять** повідомлень, які вже є в транскрипті сесії. +Буфери історії є **лише очікуваними**: вони містять групові повідомлення, які _не_ запустили виконання (наприклад, повідомлення, обмежені згадками), і **виключають** повідомлення, які вже є в транскрипті сеансу. -Вилучення директив застосовується лише до розділу **поточного повідомлення**, тож історія залишається незмінною. Канали, які обгортають історію, мають встановлювати `CommandBody` (або `RawBody`) на початковий текст повідомлення й залишати `Body` як об’єднаний промпт. Буфери історії налаштовуються через `messages.groupChat.historyLimit` (глобальне типове значення) і перевизначення для окремих каналів, як-от `channels.slack.historyLimit` або `channels.telegram.accounts..historyLimit` (установіть `0`, щоб вимкнути). +Вилучення директив застосовується лише до розділу **поточного повідомлення**, тому історія залишається неушкодженою. Канали, які обгортають історію, мають установлювати `CommandBody` (або `RawBody`) в оригінальний текст повідомлення та тримати `Body` як об’єднаний запит. Структурована історія, відповіді, переслані повідомлення та метадані каналу рендеряться як недовірені контекстні блоки з роллю користувача під час складання запиту. +Буфери історії налаштовуються через `messages.groupChat.historyLimit` (глобальне типове значення) і перевизначення для окремих каналів, як-от `channels.slack.historyLimit` або `channels.telegram.accounts..historyLimit` (установіть `0`, щоб вимкнути). -## Черга та подальші ходи +## Черги та подальші дії -Якщо виконання вже активне, вхідні повідомлення можна поставити в чергу, спрямувати в поточне виконання або зібрати для подальшого ходу. +Якщо запуск уже активний, вхідні повідомлення можна поставити в чергу, спрямувати в поточний запуск або зібрати для наступного ходу. -- Налаштовується через `messages.queue` (і `messages.queue.byChannel`). -- Типовий режим — `steer`, із 500 мс усуненням брязкоту для подальшого ходу, коли спрямування повертається до доставки подальшого ходу з черги. -- Режими: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` і застарілий режим `queue` по одному за раз. +- Налаштовуйте через `messages.queue` (і `messages.queue.byChannel`). +- Типовий режим — `steer`, із дебаунсом подальшої дії 500 мс, коли спрямування відступає до доставки подальшої дії через чергу. +- Режими: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` і застарілий режим `queue` по одному елементу за раз. Докладніше: [Черга команд](/uk/concepts/queue) і [Черга спрямування](/uk/concepts/queue-steering). -## Володіння виконанням каналу +## Володіння запуском каналу -Плагіни каналів можуть зберігати порядок, усувати брязкіт введення та застосовувати зворотний тиск транспорту до того, як повідомлення потрапить у чергу сесії. Вони не мають накладати окремий тайм-аут навколо самого ходу агента. Щойно повідомлення спрямовано до сесії, довготривала робота керується життєвими циклами сесії, інструмента та runtime, щоб усі канали послідовно повідомляли про повільні ходи й відновлювалися після них. +Plugins каналів можуть зберігати порядок, застосовувати дебаунс до введення та транспортний зворотний тиск до того, як повідомлення потрапить у чергу сеансу. Вони не повинні накладати окремий тайм-аут навколо самого ходу агента. Щойно повідомлення спрямовано до сеансу, довготривала робота керується життєвим циклом сеансу, інструмента та виконання, щоб усі канали послідовно повідомляли про повільні ходи й відновлювалися після них. -## Потокове передавання, поділ на фрагменти та пакетування +## Потокове передавання, розбиття на фрагменти та пакетування -Блокове потокове передавання надсилає часткові відповіді, коли модель створює текстові блоки. Поділ на фрагменти враховує текстові обмеження каналу та уникає розділення огородженого коду. +Блокове потокове передавання надсилає часткові відповіді, коли модель створює текстові блоки. +Розбиття на фрагменти враховує текстові обмеження каналу та уникає розриву огородженого коду. -Основні налаштування: +Ключові налаштування: - `agents.defaults.blockStreamingDefault` (`on|off`, типово вимкнено) - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) - `agents.defaults.blockStreamingCoalesce` (пакетування на основі простою) - `agents.defaults.humanDelay` (людиноподібна пауза між блоками відповідей) -- Перевизначення каналів: `*.blockStreaming` і `*.blockStreamingCoalesce` (канали, відмінні від Telegram, потребують явного `*.blockStreaming: true`) +- Перевизначення каналів: `*.blockStreaming` і `*.blockStreamingCoalesce` (канали, крім Telegram, потребують явного `*.blockStreaming: true`) -Докладніше: [Потокове передавання + поділ на фрагменти](/uk/concepts/streaming). +Докладніше: [Потокове передавання + розбиття на фрагменти](/uk/concepts/streaming). ## Видимість міркувань і токени @@ -144,34 +147,34 @@ OpenClaw може показувати або приховувати мірку Докладніше: [Директиви мислення + міркувань](/uk/tools/thinking) і [Використання токенів](/uk/reference/token-use). -## Префікси, ланцюжки та відповіді +## Префікси, гілки та відповіді Форматування вихідних повідомлень централізовано в `messages`: -- `messages.responsePrefix`, `channels..responsePrefix` і `channels..accounts..responsePrefix` (каскад вихідних префіксів), а також `channels.whatsapp.messagePrefix` (вхідний префікс WhatsApp) -- Ланцюжки відповідей через `replyToMode` і типові значення для окремих каналів +- `messages.responsePrefix`, `channels..responsePrefix` і `channels..accounts..responsePrefix` (каскад вихідних префіксів), плюс `channels.whatsapp.messagePrefix` (вхідний префікс WhatsApp) +- Прив’язка відповідей до гілки через `replyToMode` і типові значення для окремих каналів Докладніше: [Конфігурація](/uk/gateway/config-agents#messages) і документація каналів. ## Тихі відповіді Точний тихий токен `NO_REPLY` / `no_reply` означає “не доставляти видиму для користувача відповідь”. -Коли хід також має очікуване медіа інструмента, як-от згенероване TTS-аудіо, OpenClaw вилучає тихий текст, але все одно доставляє медіавкладення. +Коли хід також має очікувані медіа інструментів, наприклад згенероване TTS-аудіо, OpenClaw вилучає тихий текст, але все одно доставляє медіавкладення. OpenClaw визначає цю поведінку за типом розмови: -- Прямі розмови типово забороняють тишу й переписують голу тиху відповідь на короткий видимий резервний варіант. -- Групи/канали типово дозволяють тишу. -- Внутрішня оркестрація типово дозволяє тишу. +- Прямі розмови типово забороняють мовчання та переписують голу тиху відповідь у короткий видимий резервний варіант. +- Групи/канали типово дозволяють мовчання. +- Внутрішня оркестрація типово дозволяє мовчання. -OpenClaw також використовує тихі відповіді для внутрішніх збоїв runner, які трапляються до будь-якої відповіді асистента в непрямих чатах, щоб групи/канали не бачили шаблонний текст помилки Gateway. Прямі чати типово показують стислий текст збою; сирі деталі runner показуються лише коли `/verbose` має значення `on` або `full`. +OpenClaw також використовує тихі відповіді для внутрішніх помилок запуску, які трапляються до будь-якої відповіді асистента в непрямих чатах, щоб групи/канали не бачили шаблонного тексту помилки Gateway. Прямі чати типово показують стислий текст помилки; необроблені деталі запуску показуються лише тоді, коли `/verbose` має значення `on` або `full`. -Типові значення розміщені в `agents.defaults.silentReply` і `agents.defaults.silentReplyRewrite`; `surfaces..silentReply` і `surfaces..silentReplyRewrite` можуть перевизначати їх для окремої поверхні. +Типові значення містяться в `agents.defaults.silentReply` і `agents.defaults.silentReplyRewrite`; `surfaces..silentReply` і `surfaces..silentReplyRewrite` можуть перевизначати їх для кожної поверхні. -Коли батьківська сесія має один або більше очікуваних породжених виконань підагентів, голі тихі відповіді відкидаються на всіх поверхнях замість переписування, тож батьківська сесія залишається тихою, доки подія завершення дочірнього виконання не доставить справжню відповідь. +Коли батьківський сеанс має один або кілька очікуваних породжених запусків підагента, голі тихі відповіді відкидаються на всіх поверхнях замість переписування, тому батьківський сеанс лишається тихим, доки подія завершення дочірнього запуску не доставить справжню відповідь. ## Пов’язане - [Потокове передавання](/uk/concepts/streaming) — доставка повідомлень у реальному часі -- [Повторна спроба](/uk/concepts/retry) — поведінка повторних спроб доставки повідомлень +- [Повторна спроба](/uk/concepts/retry) — поведінка повторної спроби доставки повідомлення - [Черга](/uk/concepts/queue) — черга обробки повідомлень - [Канали](/uk/channels) — інтеграції з платформами обміну повідомленнями