chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8bd5a2a30b
commit
4e9fbe608f
File diff suppressed because it is too large
Load Diff
@ -4,25 +4,25 @@ read_when:
|
||||
summary: Стан підтримки бота Telegram, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T19:29:10Z"
|
||||
generated_at: "2026-05-03T21:05:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 06252b1540d5794aa5d8fe1066bf9d121e682a0df969a265d890445e97d5d647
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово до продакшну для особистих повідомлень ботів і груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необовʼязковий.
|
||||
Готово до продакшну для DM ботів і груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Політика особистих повідомлень за замовчуванням для Telegram — сполучення.
|
||||
Типова політика DM для Telegram — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
<Card title="Усунення несправностей каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та плейбуки відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -30,13 +30,13 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і поспілкуйтеся з **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Налаштуйте токен і політику особистих повідомлень">
|
||||
<Step title="Налаштуйте токен і політику DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише типовий обліковий запис).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть gateway і схваліть перше особисте повідомлення">
|
||||
<Step title="Запустіть gateway і підтвердьте перший DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -74,43 +74,43 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним значенням env, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує, які групові повідомлення вони отримують.
|
||||
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з двох:
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з цього:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи групи">
|
||||
Статус адміністратора керується в налаштуваннях групи Telegram.
|
||||
|
||||
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійної поведінки в групі.
|
||||
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
|
||||
- `/setjoingroups`, щоб дозволити або заборонити додавання до груп
|
||||
- `/setjoingroups`, щоб дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` для поведінки видимості в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Контроль доступу та активація
|
||||
## Керування доступом і активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика особистих повідомлень">
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
@ -118,27 +118,27 @@ openclaw pairing approve telegram <CODE>
|
||||
- `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` блокує всі особисті повідомлення та відхиляється валідацією конфігурації.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня вважається межею безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття не містить явний wildcard.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється під час валідації конфігурації.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб їх вирішити (best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви оновилися й ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (найкраща можлива спроба; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була стійко зафіксована в конфігурації (замість залежності від попередніх схвалень сполучення).
|
||||
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх підтверджень сполучення).
|
||||
|
||||
Поширене непорозуміння: схвалення сполучення для особистих повідомлень не означає «цей відправник авторизований всюди».
|
||||
Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все одно береться з явних allowlist у конфігурації.
|
||||
Якщо ви хочете «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
Типова плутанина: підтвердження сполучення DM не означає «цей відправник авторизований всюди».
|
||||
Сполучення надає доступ до DM. Якщо власника команд ще не існує, перше підтверджене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й підтвердження exec мали явний обліковий запис оператора.
|
||||
Авторизація відправників у групах і далі надходить із явних allowlist у конфігурації.
|
||||
Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
1. Напишіть своєму боту в особисті повідомлення.
|
||||
1. Надішліть DM своєму боту.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
@ -153,13 +153,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlist">
|
||||
Два механізми застосовуються разом:
|
||||
Два засоби керування застосовуються разом:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає config `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
- `groups` налаштовано: діє як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Відʼємні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень для особистих повідомлень.
|
||||
Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи чи теми.
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує підтвердження зі сховища сполучень DM.
|
||||
Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка про runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням закритий для відмови з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
@ -211,20 +211,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
Типова помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
|
||||
- Розміщуйте відʼємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Розміщуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди в дозволеній групі можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Поведінка згадок">
|
||||
Групові відповіді за замовчуванням потребують згадки.
|
||||
<Tab title="Поведінка згадки">
|
||||
Відповіді в групах за замовчуванням потребують згадки.
|
||||
|
||||
Згадка може надходити з:
|
||||
Згадка може походити з:
|
||||
|
||||
- нативної згадки `@botusername`, або
|
||||
- шаблонів згадок у:
|
||||
@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію.
|
||||
|
||||
Приклад постійної конфігурації:
|
||||
Приклад сталої конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -254,9 +254,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Отримання ID групового чату:
|
||||
|
||||
- переслати групове повідомлення до `@userinfobot` / `@getidsbot`
|
||||
- або прочитати `chat.id` з `openclaw logs --follow`
|
||||
- або переглянути Bot API `getUpdates`
|
||||
- перешліть групове повідомлення до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перегляньте Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -265,31 +265,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та placeholders для медіа.
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми залишалися ізольованими.
|
||||
- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але за замовчуванням залишає особисті повідомлення у пласкій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій за темами в особистих повідомленнях.
|
||||
- Довге опитування використовує grammY runner із послідовністю за чатом і потоком. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший gateway OpenClaw, скрипт або зовнішній poller, імовірно, використовує той самий токен.
|
||||
- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час тривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується).
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID треду для відповідей, але за замовчуванням залишає DM у плоскій сесії. Налаштуйте `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` або відповідну конфігурацію теми, коли ви навмисно хочете ізоляцію сесій тем DM.
|
||||
- Довге опитування використовує grammY runner із послідовністю за чатами/тредами. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота за раз. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший OpenClaw gateway, скрипт або зовнішній poller використовує той самий токен.
|
||||
- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеного liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через polling-stall під час тривалої роботи. Значення вказується в мілісекундах і допускається від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник можливостей
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може stream-ити часткові відповіді в реальному часі:
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` відповідає `partial` у Telegram (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний streaming попереднього перегляду)
|
||||
- `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зберігає один редагований статусний чернетковий текст і оновлює його прогресом інструментів до фінальної доставки
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активне потокове передавання попереднього перегляду)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення плану або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і новіших версій. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки статусу, що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніших версій. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,42 +306,42 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібно доставляти тільки фінальну відповідь: редагування прев’ю в Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання окремих повідомлень «Працюю...». Запити на схвалення, медіа-вміст і помилки все одно проходять через звичайне фінальне доставлення. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно залишити лише редагування прев’ю відповіді, приховавши рядки стану прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду в Telegram вимикається, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремих статусних повідомлень. Запити на підтвердження, медіавміст і помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
|
||||
<Note>
|
||||
Відповіді на вибрані цитати в Telegram є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить текст вибраної цитати, OpenClaw надсилає фінальну відповідь через нативний шлях відповіді на цитату в Telegram замість редагування прев’ю відповіді, тому `streaming.preview.toolProgress` не може показати короткі рядки «Працюю...» для цього звернення. Відповіді на поточне повідомлення без тексту вибраної цитати все одно зберігають потокове прев’ю. Установіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді на цитати, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс.
|
||||
Відповіді Telegram на вибрані цитати є винятком. Коли `replyToMode` має значення `"first"`, `"all"` або `"batched"` і вхідне повідомлення містить вибраний текст цитати, OpenClaw надсилає фінальну відповідь через нативний шлях відповіді з цитуванням Telegram замість редагування попереднього перегляду відповіді, тому `streaming.preview.toolProgress` не може показувати короткі рядки статусу для цього ходу. Відповіді на поточне повідомлення без вибраного тексту цитати й далі зберігають потоковий попередній перегляд. Установіть `replyToMode: "off"`, коли видимість прогресу інструментів важливіша за нативні відповіді з цитуванням, або встановіть `streaming.preview.toolProgress: false`, щоб явно прийняти цей компроміс.
|
||||
</Note>
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
Для текстових відповідей:
|
||||
|
||||
- короткі прев’ю в DM/групах/темах: OpenClaw зберігає те саме повідомлення прев’ю й виконує фінальне редагування на місці, якщо після появи прев’ю не було надіслано видимого повідомлення, що не є прев’ю
|
||||
- прев’ю, після яких іде видимий вивід, що не є прев’ю: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення й прибирає старіше прев’ю, тож фінальна відповідь з’являється після проміжного виводу
|
||||
- прев’ю, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає прев’ю, тож видима часова позначка Telegram відображає час завершення, а не час створення прев’ю
|
||||
- короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці, якщо після появи попереднього перегляду не було надіслано видиме повідомлення, що не є попереднім переглядом
|
||||
- попередні перегляди, після яких іде видимий вивід, що не є попереднім переглядом: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення й очищає старіший попередній перегляд, тому фінальна відповідь з'являється після проміжного виводу
|
||||
- попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тому видима часова позначка Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайного фінального доставлення, а потім прибирає повідомлення прев’ю.
|
||||
Для складних відповідей (наприклад медіавмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Потокове прев’ю відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік прев’ю, щоб уникнути подвійного потокового передавання.
|
||||
Потоковий попередній перегляд відокремлений від потокової передачі блоків. Коли потокову передачу блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового надсилання.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
Потік reasoning тільки для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування в живе прев’ю під час генерування
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
- `/reasoning stream` надсилає reasoning у живий попередній перегляд під час генерації
|
||||
- фінальна відповідь надсилається без тексту reasoning
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування й резервний HTML">
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown відображається як безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram.
|
||||
- Markdown-подібний текст рендериться у безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Прев’ю посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди й користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`.
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
|
||||
@ -364,47 +364,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- назви нормалізуються (початковий `/` видаляється, літери переводяться в нижній регістр)
|
||||
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й записуються в журнал
|
||||
- конфлікти/дублікати пропускаються й журналюються
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills усе одно можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- команди plugin/skill усе одно можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Користувацькі команди або команди Plugin усе ще можуть реєструватися, якщо налаштовані.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо налаштовані.
|
||||
|
||||
Поширені помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнювалося після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повний endpoint `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як збій очищення Webhook.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані.
|
||||
- `setMyCommands failed` із `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнювалося після обрізання; зменште кількість plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` із `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повний endpoint `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється перед polling, тому це не повідомляється як збій очищення webhook.
|
||||
- `setMyCommands failed` із помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
|
||||
|
||||
### Команди сполучення пристрою (Plugin `device-pair`)
|
||||
### Команди сполучення пристрою (`device-pair` plugin)
|
||||
|
||||
Коли Plugin `device-pair` установлено:
|
||||
Коли встановлено `device-pair` plugin:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список запитів, що очікують (зокрема роль/області дії)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
3. `/pair pending` перелічує запити в очікуванні (зокрема роль/scopes)
|
||||
4. підтвердьте запит:
|
||||
- `/pair approve <requestId>` для явного підтвердження
|
||||
- `/pair approve`, коли є лише один запит в очікуванні
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області дії під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий операторський токен лишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-scope мають префікс ролі, тому цей allowlist оператора задовольняє лише операторські запити; неоператорським ролям усе ще потрібні scopes під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роллю/областями дії/відкритим ключем), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад роль/scopes/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед підтвердженням.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані кнопки">
|
||||
Налаштуйте область дії вбудованої клавіатури:
|
||||
Налаштуйте область дії inline-клавіатури:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -442,7 +442,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `dm`
|
||||
- `group`
|
||||
- `all`
|
||||
- `allowlist` (типово)
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
|
||||
@ -472,63 +472,63 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов'язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов'язкові `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Дії повідомлень каналу надають ергономічні псевдоніми (`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.*`.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ситуативне повторне розв’язання SecretRef для кожного надсилання.
|
||||
Runtime-надсилання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв'язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги потоків відповідей">
|
||||
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги threading для відповідей">
|
||||
Telegram підтримує явні теги reply threading у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, яке спричинило запуск
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
|
||||
- `off` (типово)
|
||||
- `off` (за замовчуванням)
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Коли потоки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
Коли reply threading увімкнено й доступний оригінальний текст або підпис Telegram, OpenClaw автоматично включає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
Примітка: `off` вимикає неявний reply threading. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму й поведінка потоків">
|
||||
Супергрупи форумів:
|
||||
<Accordion title="Теми форуму та поведінка потоків">
|
||||
Форумні супергрупи:
|
||||
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору спрямовуються до потоку теми
|
||||
- шлях конфігурації теми:
|
||||
- ключі сесій теми додають `:topic:<threadId>`
|
||||
- відповіді та typing спрямовуються в потік теми
|
||||
- шлях config теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Особливий випадок загальної теми (`threadId=1`):
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору все одно включають `message_thread_id`
|
||||
- дії typing усе ще включають `message_thread_id`
|
||||
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише до теми й не успадковується з типових значень групи.
|
||||
Наслідування теми: записи теми наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` є лише тематичним і не наслідується з типових значень групи.
|
||||
|
||||
**Маршрутизація агентів за темами**: кожна тема може маршрутизуватися до іншого агента через установлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента через установлення `agentId` у config теми. Це дає кожній темі власний ізольований workspace, пам'ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -550,24 +550,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійне прив’язування тем ACP**: теми форумів можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, наприклад `-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 <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження породження в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (типово: `true`).
|
||||
**Прив'язаний до потоку ACP spawn із чату**: `/acp spawn <agent> --thread here|auto` прив'язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження spawn у темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` лишалося ввімкненим (за замовчуванням: `true`).
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають маршрутизацію DM і метадані відповіді в пласких сесіях; вони використовують ключі сесій із підтримкою потоків лише коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідну конфігурацію теми. Використовуйте `channels.telegram.dm.threadReplies` верхнього рівня як типове значення облікового запису або `direct.<chatId>.threadReplies` для одного DM.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` за замовчуванням зберігають DM-маршрутизацію та метадані відповіді у плоских сесіях; вони використовують ключі сесій з урахуванням потоків лише тоді, коли налаштовано `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідний config теми. Використовуйте верхньорівневий `channels.telegram.dm.threadReplies` для типового значення облікового запису або `direct.<chatId>.threadReplies` для одного DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Аудіо, відео й стікери">
|
||||
<Accordion title="Аудіо, відео та стікери">
|
||||
### Аудіоповідомлення
|
||||
|
||||
Telegram розрізняє голосові нотатки й аудіофайли.
|
||||
Telegram розрізняє голосові повідомлення та аудіофайли.
|
||||
|
||||
- типово: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку
|
||||
- транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований,
|
||||
ненадійний текст; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати.
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосове повідомлення
|
||||
- транскрипти вхідних голосових повідомлень оформлюються як машинно згенерований,
|
||||
недовірений текст у контексті агента; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з mention-gating продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -619,7 +619,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити повторні виклики розпізнавання зображень.
|
||||
|
||||
Увімкнути дії зі стікерами:
|
||||
|
||||
@ -659,31 +659,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reaction notifications">
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
Конфігурація:
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (стандартно: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (стандартно: `minimal`)
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`)
|
||||
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращою спробою через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно враховують засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори тредів в оновленнях реакцій.
|
||||
- нефорумні групи спрямовуються до сеансу групового чату
|
||||
- форумні групи спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращої спроби через кеш надісланих повідомлень).
|
||||
- Події реакцій усе ще поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори гілок в оновленнях реакцій.
|
||||
- групи не форумного типу спрямовуються до сесії групового чату
|
||||
- форумні групи спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
`allowed_updates` для polling/webhook автоматично містить `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ack reactions">
|
||||
<Accordion title="Реакції підтвердження">
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
@ -700,12 +700,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Config writes from Telegram events and commands">
|
||||
Записи конфігурації каналу ввімкнені стандартно (`configWrites !== false`).
|
||||
<Accordion title="Записи конфігурації з подій і команд Telegram">
|
||||
Записи конфігурації каналу ввімкнено типово (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
Записи, ініційовані Telegram, охоплюють:
|
||||
|
||||
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потрібне ввімкнення команд)
|
||||
|
||||
Вимкнути:
|
||||
@ -722,32 +722,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
Стандартно використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов'язкові `webhookPath`, `webhookHost`, `webhookPort` (стандартні значення `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling проти webhook">
|
||||
Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типово `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив'язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі лінії бота для кожного чату/теми, що використовуються long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
Режим webhook перевіряє захист запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі доріжки бота для кожного чату/теми, що й long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limits, retry, and CLI targets">
|
||||
- Стандартне значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (стандартно 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (стандартно 500) керує тим, як довго альбоми/медіагрупи Telegram буферизуються перед тим, як OpenClaw надсилає їх як одне вхідне повідомлення. Збільште це значення, якщо частини альбому надходять із запізненням; зменште його, щоб скоротити затримку відповіді на альбом.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає час очікування клієнта Telegram API (якщо не задано, застосовується стандарт grammY). Клієнти ботів обмежують налаштовані значення, нижчі за 60-секундний захист вихідних запитів тексту/набирання, щоб grammY не переривав видиму доставку відповіді до того, як зможуть спрацювати транспортний захист і fallback OpenClaw. Long polling усе одно використовує 45-секундний захист запиту `getUpdates`, щоб неактивні опитування не залишалися покинутими безстроково.
|
||||
- `channels.telegram.pollingStallThresholdMs` стандартно має значення `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (стандартно 50); `0` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий.
|
||||
- allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
<Accordion title="Обмеження, повторні спроби та цілі CLI">
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (типово 500) керує тим, як довго альбоми/медіагрупи Telegram буферизуються, перш ніж OpenClaw передасть їх як одне вхідне повідомлення. Збільште це значення, якщо частини альбому надходять із запізненням; зменште його, щоб скоротити затримку відповіді на альбом.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів обмежують налаштовані значення нижче 60-секундного захисту вихідних запитів тексту/набору, щоб grammY не переривав доставку видимої відповіді до того, як спрацює транспортний захист і резервний механізм OpenClaw. Long polling усе ще використовує 45-секундний захист запиту `getUpdates`, щоб неактивні опитування не залишалися покинутими безкінечно.
|
||||
- `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отримано.
|
||||
- allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Елементи керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Конфігурація `channels.telegram.retry` застосовується до помічників надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставка фінальної відповіді для вхідних повідомлень також використовує обмежений повтор safe-send для збоїв Telegram до підключення, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення.
|
||||
- Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставка фінальної відповіді для вхідних повідомлень також використовує обмежений повтор безпечного надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або ім'ям користувача:
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -769,7 +769,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для форумних тем (або використайте ціль `:topic:`)
|
||||
- `--thread-id` для форумних тем (або використовуйте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
@ -780,25 +780,25 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
Обмеження дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec approvals in Telegram">
|
||||
Telegram підтримує схвалення exec у DM схвалювачів і може необов'язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Схвалення exec у Telegram">
|
||||
Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача)
|
||||
- `channels.telegram.execApprovals.approvers` (відступає до числових ID власників із `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (стандартно) | `channel` | `both`
|
||||
- `channels.telegram.execApprovals.approvers` (повертається до числових ID власників із `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може спілкуватися з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене спарювання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене сполучення DM початково заповнює `commands.ownerAllowFrom`, коли власника команд ще немає, тому налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`.
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Схвалення exec стандартно спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Схвалення exec типово спливають через 30 хвилин.
|
||||
|
||||
Кнопки inline-схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення plugin; інші спершу визначаються через схвалення exec.
|
||||
Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалення з префіксом `plugin:` визначаються через схвалення plugin; інші спершу визначаються через схвалення exec.
|
||||
|
||||
Див. [Схвалення exec](/uk/tools/exec-approvals).
|
||||
|
||||
@ -807,14 +807,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
## Елементи керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або приховати його. Цю поведінку контролюють два ключі конфігурації:
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Цією поведінкою керують два ключі конфігурації:
|
||||
|
||||
| Ключ | Значення | Стандартно | Опис |
|
||||
| ----------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю пригнічує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилками під час збоїв. |
|
||||
| Ключ | Значення | Типово | Опис |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилками під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (таке саме успадкування, як і для інших ключів конфігурації Telegram).
|
||||
Підтримуються перевизначення для кожного облікового запису, групи та теми (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -835,56 +835,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bot does not respond to non mention group messages">
|
||||
<Accordion title="Бот не відповідає на групові повідомлення без згадки">
|
||||
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сеансу: `/activation always`.
|
||||
- швидка перевірка сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot not seeing group messages at all">
|
||||
<Accordion title="Бот взагалі не бачить групові повідомлення">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або включати `"*"`)
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Commands work partially or not at all">
|
||||
<Accordion title="Команди працюють частково або не працюють зовсім">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (спарювання та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
|
||||
- авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню
|
||||
- стартові виклики `deleteMyCommands` / `setMyCommands` і виклики набирання `sendChatAction` обмежені й повторюються один раз через транспортний fallback Telegram у разі тайм-ауту запиту. Постійні мережеві/fetch-помилки зазвичай указують на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
- стартові виклики `deleteMyCommands` / `setMyCommands` і виклики набору `sendChatAction` обмежені й повторюються один раз через транспортний резерв Telegram у разі тайм-ауту запиту. Постійні мережеві/fetch-помилки зазвичай вказують на проблеми досяжності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Startup reports unauthorized token">
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований токен">
|
||||
|
||||
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте заново токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "Webhook не існує" лише відкладе той самий збій через неправильний токен до пізніших викликів API.
|
||||
- Повторно скопіюйте або згенеруйте заново токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для стандартного облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як «Webhook не існує» лише відклало б той самий збій через поганий токен до пізніших викликів API.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polling or network instability">
|
||||
<Accordion title="Опитування або нестабільність мережі">
|
||||
|
||||
- Node 22+ і власний fetch/proxy можуть спричинити негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
|
||||
- Під час запуску polling OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, тому runner не потребує другого `getMe` перед першим `getUpdates`.
|
||||
- Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час запуску polling, OpenClaw переходить до long polling замість виконання ще одного контрольного виклику перед polling. Webhook, який усе ще активний, проявляється як конфлікт `getUpdates`; після цього OpenClaw перебудовує транспорт Telegram і повторює очищення Webhook.
|
||||
- Якщо сокети Telegram перевикористовуються за коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення нижче за захисні межі вихідних запитів і `getUpdates`, але старіші випуски могли переривати кожен polling або відповідь, коли це значення було нижче за ці межі.
|
||||
- Якщо журнали містять `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 між хостом і `api.telegram.org`.
|
||||
- Node 22+ і власний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки.
|
||||
- Під час запуску опитування OpenClaw повторно використовує успішну стартову перевірку `getMe` для grammY, тож виконавцю не потрібен другий `getMe` перед першим `getUpdates`.
|
||||
- Якщо `deleteWebhook` завершується збоєм через тимчасову мережеву помилку під час запуску опитування, OpenClaw переходить до long polling замість ще одного передопитувального виклику площини керування. Якщо Webhook усе ще активний, це проявляється як конфлікт `getUpdates`; OpenClaw тоді перебудовує транспорт Telegram і повторює очищення Webhook.
|
||||
- Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів обмежують налаштовані значення нижче захисних меж вихідних запитів і `getUpdates`, але старіші випуски могли переривати кожне опитування або відповідь, коли це значення було нижчим за ці межі.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw типово перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll.
|
||||
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис опитування не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис Webhook не завершив `setWebhook` після стартового пільгового періоду, або коли остання успішна активність транспорту опитування застаріла.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` працюють нормально, але ваш хост усе ще повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або вихідним TLS між хостом і `api.telegram.org`.
|
||||
- Telegram також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартні змінні середовища proxy відсутні, Telegram також використовує цю URL-адресу для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й немає стандартних змінних середовища proxy, Telegram також використовує цей URL для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -892,8 +892,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім типовий порядок процесу, наприклад `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства:
|
||||
- Node 22+ типово використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS для Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім стандарт процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`.
|
||||
- Якщо ваш хост є WSL2 або явно краще працює в режимі лише IPv4, примусово задайте вибір сімейства:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -902,7 +902,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону для бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете
|
||||
@ -915,18 +915,18 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Те саме явне ввімкнення доступне для кожного облікового запису в
|
||||
- Така сама опція доступна для окремого облікового запису за адресою
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy розв’язує медіахости Telegram у `198.18.x.x`, спочатку залиште
|
||||
- Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
|
||||
бенчмарків RFC 2544 за замовчуванням.
|
||||
RFC 2544 для бенчмаркінгу за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
|
||||
медіа від SSRF. Використовуйте його лише для довірених середовищ proxy,
|
||||
контрольованих оператором, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном бенчмарків
|
||||
RFC 2544. Залишайте його вимкненим для звичайного доступу Telegram через публічний інтернет.
|
||||
від SSRF для медіа. Використовуйте це лише для довірених середовищ proxy,
|
||||
контрольованих оператором, як-от Clash, Mihomo або маршрутизація fake-IP у Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном RFC 2544 для бенчмаркінгу.
|
||||
Для звичайного публічного доступу Telegram через інтернет залишайте це вимкненим.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення середовища (тимчасові):
|
||||
@ -943,23 +943,23 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Додаткова допомога: [усунення неполадок каналів](/uk/channels/troubleshooting).
|
||||
Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="High-signal Telegram fields">
|
||||
<Accordion title="Високосигнальні поля Telegram">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- схвалення виконання: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`)
|
||||
- затвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки/відповіді: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставлення: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot<TOKEN>`)
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
@ -969,28 +969,28 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритет кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити типову маршрутизацію явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, і `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити стандартну маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
|
||||
Зв’яжіть користувача Telegram із Gateway.
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Сполучіть користувача Telegram із Gateway.
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка списку дозволених груп і тем.
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/uk/channels/channel-routing">
|
||||
<Card title="Маршрутизація каналів" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/uk/gateway/security">
|
||||
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і посилення захисту.
|
||||
</Card>
|
||||
<Card title="Multi-agent routing" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставте групи й теми з агентами.
|
||||
<Card title="Маршрутизація кількох агентів" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставляйте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
<Card title="Усунення несправностей" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
293
docs/uk/concepts/progress-drafts.md
Normal file
293
docs/uk/concepts/progress-drafts.md
Normal file
@ -0,0 +1,293 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування видимих оновлень перебігу для тривалих ходів чату
|
||||
- Вибір між режимами часткового, блокового потокового передавання та потокового передавання прогресу
|
||||
- Пояснення того, як OpenClaw оновлює одне повідомлення каналу під час виконання роботи
|
||||
- Усунення несправностей із чернетками перебігу виконання, окремими повідомленнями про перебіг виконання або резервним механізмом фіналізації
|
||||
summary: 'Чернетки прогресу: одне видиме повідомлення про роботу, що триває, яке оновлюється під час роботи агента'
|
||||
title: Чернетки прогресу
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:05:52Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c
|
||||
source_path: concepts/progress-drafts.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Чернетки перебігу роботи роблять тривалі ходи агента живими в чаті, не перетворюючи
|
||||
розмову на стос тимчасових відповідей зі статусом.
|
||||
|
||||
Коли чернетки перебігу роботи увімкнені, OpenClaw створює одне видиме повідомлення
|
||||
про роботу в процесі, оновлює його, поки агент читає, планує, викликає інструменти
|
||||
або чекає на схвалення, а потім перетворює цю чернетку на фінальну відповідь,
|
||||
коли канал може зробити це безпечно.
|
||||
|
||||
```text
|
||||
Shelling
|
||||
- reading recent channel context
|
||||
- checking matching issues
|
||||
- preparing reply
|
||||
```
|
||||
|
||||
Використовуйте чернетки перебігу роботи, коли потрібне одне охайне повідомлення
|
||||
зі статусом під час роботи з багатьма інструментами та фінальна відповідь після
|
||||
завершення ходу.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
Увімкніть чернетки перебігу роботи для кожного каналу через `streaming.mode: "progress"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Зазвичай цього достатньо. OpenClaw вибере автоматичну однослівну мітку, додаватиме
|
||||
стислі рядки перебігу, поки відбувається корисна робота, і приглушить дубльовані
|
||||
окремі повідомлення про перебіг для цього ходу.
|
||||
|
||||
## Що бачать користувачі
|
||||
|
||||
Чернетка перебігу роботи має дві частини:
|
||||
|
||||
| Частина | Призначення |
|
||||
| --------------- | ---------------------------------------------------------------- |
|
||||
| Мітка | Короткий заголовок, наприклад `Thinking` або `Shelling`. |
|
||||
| Рядки перебігу | Стислі оновлення запуску, як-от виклики інструментів, кроки завдання або схвалення. |
|
||||
|
||||
Мітка з'являється одразу, коли агент починає відповідати. Рядки перебігу додаються
|
||||
лише тоді, коли агент надсилає корисні оновлення про роботу. Фінальна відповідь
|
||||
замінює чернетку, коли це можливо; інакше OpenClaw надсилає фінальну відповідь
|
||||
звичайним способом і очищає або припиняє оновлювати чернетку відповідно до транспорту каналу.
|
||||
|
||||
## Вибір режиму
|
||||
|
||||
`channels.<channel>.streaming.mode` керує видимою поведінкою роботи в процесі:
|
||||
|
||||
| Режим | Найкраще для | Що з'являється в чаті |
|
||||
| ---------- | ------------------------------------ | -------------------------------------------------- |
|
||||
| `off` | Тихі канали | Лише фінальна відповідь. |
|
||||
| `partial` | Спостереження за появою тексту відповіді | Одна чернетка, яку редагують найновішим текстом відповіді. |
|
||||
| `block` | Більші фрагменти попереднього перегляду відповіді | Один попередній перегляд, що оновлюється або доповнюється більшими фрагментами. |
|
||||
| `progress` | Ходи з багатьма інструментами або тривалі ходи | Одна чернетка статусу, потім фінальна відповідь. |
|
||||
|
||||
Виберіть `progress`, коли користувачам важливіше "що відбувається", ніж спостерігати,
|
||||
як текст відповіді транслюється токен за токеном.
|
||||
|
||||
Виберіть `partial`, коли сама відповідь є сигналом перебігу.
|
||||
|
||||
Виберіть `block`, коли потрібні оновлення попереднього перегляду чернетки більшими
|
||||
текстовими фрагментами. У Discord і Telegram `streaming.mode: "block"` усе ще є
|
||||
потоковим попереднім переглядом, а не звичайною доставкою блоками. Використовуйте
|
||||
`streaming.block.enabled` або застарілий `blockStreaming`, коли потрібні звичайні
|
||||
блокові відповіді.
|
||||
|
||||
## Налаштування міток
|
||||
|
||||
Мітки перебігу роботи містяться в `channels.<channel>.streaming.progress`.
|
||||
|
||||
Типова мітка — `auto`, яка вибирає з вбудованого в OpenClaw набору однослівних
|
||||
міток:
|
||||
|
||||
```text
|
||||
Thinking
|
||||
Shelling
|
||||
Scuttling
|
||||
Clawing
|
||||
Pinching
|
||||
Molting
|
||||
Bubbling
|
||||
Tiding
|
||||
Reefing
|
||||
Cracking
|
||||
Sifting
|
||||
Brining
|
||||
Nautiling
|
||||
Krilling
|
||||
Barnacling
|
||||
Lobstering
|
||||
Tidepooling
|
||||
Pearling
|
||||
Snapping
|
||||
Surfacing
|
||||
```
|
||||
|
||||
Використайте фіксовану мітку:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
label: "Investigating",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Використайте власний автоматичний набір міток:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
label: "auto",
|
||||
labels: ["Checking", "Reading", "Testing", "Finishing"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Приховайте мітку й показуйте лише рядки перебігу:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
label: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Керування рядками перебігу
|
||||
|
||||
Рядки перебігу ввімкнені типово в режимі перебігу. Вони походять із реальних
|
||||
подій запуску: запусків інструментів, оновлень елементів, планів завдань,
|
||||
схвалень, виводу команд, підсумків патчів і подібної активності агента.
|
||||
|
||||
Обмежте кількість рядків, що залишаються видимими:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
maxLines: 4,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Збережіть одну чернетку перебігу, але приховайте рядки інструментів і завдань:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
toolProgress: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
З `toolProgress: false` OpenClaw усе одно приглушує старі окремі повідомлення
|
||||
про перебіг інструментів для цього ходу. Канал залишається візуально тихим до
|
||||
фінальної відповіді, за винятком мітки, якщо її налаштовано.
|
||||
|
||||
## Поведінка каналів
|
||||
|
||||
Кожен канал використовує найохайніший транспорт, який він підтримує:
|
||||
|
||||
| Канал | Транспорт перебігу | Примітки |
|
||||
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
|
||||
| Discord | Надіслати одне повідомлення, потім редагувати його. | Фінальний текст редагується на місці, коли вміщується в одне безпечне повідомлення попереднього перегляду. |
|
||||
| Matrix | Надіслати одну подію, потім редагувати її. | Конфігурація потокової передачі на рівні облікового запису керує чернетками на рівні облікового запису. |
|
||||
| Microsoft Teams | Нативний потік Teams в особистих чатах. | `streaming.mode: "block"` зіставляється з блоковою доставкою Teams. |
|
||||
| Slack | Нативний потік або редагований допис-чернетка. | Доступність гілки впливає на те, чи можна використовувати нативну потокову передачу. |
|
||||
| Telegram | Надіслати одне повідомлення, потім редагувати його. | Старі видимі чернетки можуть замінюватися, щоб фінальні часові позначки залишалися корисними. |
|
||||
| Mattermost | Редагований допис-чернетка. | Активність інструментів згортається в той самий допис у стилі чернетки. |
|
||||
|
||||
Канали без безпечної підтримки редагування зазвичай повертаються до індикаторів
|
||||
набору тексту або доставки лише фінальної відповіді.
|
||||
|
||||
## Фіналізація
|
||||
|
||||
Коли фінальна відповідь готова, OpenClaw намагається зберегти чат чистим:
|
||||
|
||||
- Якщо чернетка може безпечно стати фінальною відповіддю, OpenClaw редагує її на місці.
|
||||
- Якщо канал використовує нативну потокову передачу перебігу, OpenClaw фіналізує
|
||||
цей потік, коли нативний транспорт приймає фінальний текст.
|
||||
- Якщо фінальна відповідь містить медіа, запит на схвалення, явну ціль відповіді,
|
||||
забагато фрагментів або невдале редагування/надсилання, OpenClaw надсилає фінальну
|
||||
відповідь через звичайний шлях доставки каналу.
|
||||
|
||||
Резервний шлях навмисний. Краще надіслати нову фінальну відповідь, ніж втратити
|
||||
текст, помилково прив'язати відповідь до гілки або перезаписати чернетку корисним
|
||||
навантаженням, яке канал не може безпечно представити.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
**Я бачу лише фінальну відповідь.**
|
||||
|
||||
Перевірте, що `channels.<channel>.streaming.mode` встановлено на `progress` для
|
||||
облікового запису або каналу, який обробив повідомлення. Деякі групові шляхи або
|
||||
шляхи відповіді з цитуванням можуть вимкнути попередній перегляд чернетки для
|
||||
ходу, коли канал не може безпечно редагувати правильне повідомлення.
|
||||
|
||||
**Я бачу мітку, але не бачу рядків інструментів.**
|
||||
|
||||
Перевірте `streaming.progress.toolProgress`. Якщо значення `false`, OpenClaw
|
||||
зберігає поведінку однієї чернетки, але приховує рядки перебігу інструментів і завдань.
|
||||
|
||||
**Я бачу нове фінальне повідомлення замість відредагованої чернетки.**
|
||||
|
||||
Це резервний механізм безпеки. Це може трапитися для відповідей із медіа, довгих
|
||||
відповідей, явних цілей відповіді, старих чернеток Telegram, відсутніх цілей гілок
|
||||
Slack, видалених повідомлень попереднього перегляду або невдалої фіналізації нативного потоку.
|
||||
|
||||
**Я все ще бачу окремі повідомлення про перебіг.**
|
||||
|
||||
Режим перебігу приглушує типові окремі повідомлення про перебіг інструментів,
|
||||
коли чернетка активна. Якщо окремі повідомлення все ще з'являються, перевірте,
|
||||
що хід справді використовує режим перебігу, а не `streaming.mode: "off"` або шлях
|
||||
каналу, який не може створити чернетку для цього повідомлення.
|
||||
|
||||
**Teams поводиться інакше, ніж Discord або Telegram.**
|
||||
|
||||
Microsoft Teams використовує нативний потік в особистих чатах замість універсального
|
||||
транспорту попереднього перегляду з надсиланням і редагуванням. Teams також трактує
|
||||
`streaming.mode: "block"` як блокову доставку Teams, оскільки не має такого самого
|
||||
блокового режиму попереднього перегляду чернеток, який використовують Discord і Telegram.
|
||||
|
||||
## Пов'язане
|
||||
|
||||
- [Потокова передача й фрагментація](/uk/concepts/streaming)
|
||||
- [Повідомлення](/uk/concepts/messages)
|
||||
- [Конфігурація каналів](/uk/gateway/config-channels)
|
||||
- [Discord](/uk/channels/discord)
|
||||
- [Matrix](/uk/channels/matrix)
|
||||
- [Microsoft Teams](/uk/channels/msteams)
|
||||
- [Slack](/uk/channels/slack)
|
||||
- [Telegram](/uk/channels/telegram)
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Пояснення того, як потокове передавання або розбиття на фрагменти працює в каналах
|
||||
- Зміна поведінки потокового передавання блоків або розбиття каналу на фрагменти
|
||||
- Налагодження дубльованих/передчасних блокових відповідей або потокового передавання попереднього перегляду каналу
|
||||
summary: Поведінка потокового передавання та розбиття на фрагменти (блокові відповіді, потокове передавання попереднього перегляду каналу, зіставлення режимів)
|
||||
title: Потокове передавання та розбиття на фрагменти
|
||||
- Пояснення роботи потокової передачі або розбиття на фрагменти в каналах
|
||||
- Зміна поведінки блокового потокового передавання або фрагментації каналів
|
||||
- Налагодження дубльованих/передчасних блокових відповідей або потокового попереднього перегляду каналу
|
||||
summary: Поведінка потокового передавання + поділу на фрагменти (блокові відповіді, потокове передавання попереднього перегляду каналу, зіставлення режимів)
|
||||
title: Потокове передавання та поділ на фрагменти
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T15:48:04Z"
|
||||
generated_at: "2026-05-03T21:05:45Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4a62b333123d317cad9a8063a68c5c026fb91b23731a6ccdb97d995d9bb8bdba
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw має два окремі рівні потокової передачі:
|
||||
OpenClaw має два окремі шари потокового передавання:
|
||||
|
||||
- **Потокова передача блоків (канали):** надсилає завершені **блоки** під час написання асистентом. Це звичайні повідомлення каналів (не дельти токенів).
|
||||
- **Потоковий попередній перегляд (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації.
|
||||
- **Потокове передавання блоків (канали):** надсилає завершені **блоки** під час написання відповіді асистентом. Це звичайні повідомлення каналу (не дельти токенів).
|
||||
- **Потокове передавання попереднього перегляду (Telegram/Discord/Slack):** оновлює тимчасове **повідомлення попереднього перегляду** під час генерації.
|
||||
|
||||
Сьогодні **справжньої потокової передачі дельт токенів** у повідомлення каналів немає. Потоковий попередній перегляд працює на основі повідомлень (надсилання + редагування/додавання).
|
||||
Сьогодні **справжнього потокового передавання дельт токенів** у повідомлення каналів немає. Потокове передавання попереднього перегляду працює на основі повідомлень (надсилання + редагування/додавання).
|
||||
|
||||
## Потокова передача блоків (повідомлення каналів)
|
||||
## Потокове передавання блоків (повідомлення каналу)
|
||||
|
||||
Потокова передача блоків надсилає вивід асистента великими фрагментами в міру їх появи.
|
||||
Потокове передавання блоків надсилає вивід асистента грубими фрагментами в міру його появи.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -35,107 +35,112 @@ Model output
|
||||
└─ channel send (block replies)
|
||||
```
|
||||
|
||||
Легенда:
|
||||
Позначення:
|
||||
|
||||
- `text_delta/events`: події потоку моделі (можуть бути розрідженими для непотокових моделей).
|
||||
- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + бажаний розрив.
|
||||
- `text_delta/events`: події потоку моделі (можуть бути розрідженими для моделей без потокового передавання).
|
||||
- `chunker`: `EmbeddedBlockChunker`, що застосовує мінімальні/максимальні межі + бажану точку розбиття.
|
||||
- `channel send`: фактичні вихідні повідомлення (блокові відповіді).
|
||||
|
||||
**Елементи керування:**
|
||||
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (типово вимкнено).
|
||||
- Перевизначення каналів: `*.blockStreaming` (і варіанти для окремих акаунтів), щоб примусово встановити `"on"`/`"off"` для кожного каналу.
|
||||
- Перевизначення каналів: `*.blockStreaming` (і варіанти для окремих облікових записів), щоб примусово встановити `"on"`/`"off"` для кожного каналу.
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` або `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
|
||||
- `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`, тому наприкінці може видати кілька фрагментів.
|
||||
|
||||
### Доставка медіа з потоковою передачею блоків
|
||||
### Доставлення медіа з потоковим передаванням блоків
|
||||
|
||||
Директиви `MEDIA:` є звичайними метаданими доставки. Коли потокова передача блоків рано надсилає медіаблок, OpenClaw запам’ятовує цю доставку для поточного ходу. Якщо фінальне навантаження асистента повторює ту саму URL-адресу медіа, фінальна доставка вилучає дубльоване медіа замість повторного надсилання вкладення.
|
||||
Директиви `MEDIA:` є звичайними метаданими доставлення. Коли потокове передавання блоків рано надсилає медіаблок, OpenClaw запам’ятовує це доставлення для поточного ходу. Якщо фінальне корисне навантаження асистента повторює той самий URL медіа, фінальне доставлення вилучає дубльоване медіа замість повторного надсилання вкладення.
|
||||
|
||||
Точні дублікати фінальних навантажень пригнічуються. Якщо фінальне навантаження додає окремий текст навколо медіа, яке вже було передано потоком, OpenClaw усе одно надсилає новий текст, зберігаючи медіа як одноразову доставку. Це запобігає дублюванню голосових нотаток або файлів у каналах на кшталт Telegram, коли агент видає `MEDIA:` під час потокової передачі, а провайдер також включає його в завершену відповідь.
|
||||
Точні дублікати фінальних корисних навантажень пригнічуються. Якщо фінальне корисне навантаження додає окремий текст навколо медіа, яке вже було передано потоком, OpenClaw все одно надсилає новий текст, зберігаючи медіа як одноразове доставлення. Це запобігає дублюванню голосових нотаток або файлів у таких каналах, як Telegram, коли агент видає `MEDIA:` під час потокового передавання, а провайдер також включає його в завершену відповідь.
|
||||
|
||||
## Алгоритм фрагментації (нижні/верхні межі)
|
||||
## Алгоритм фрагментації (нижня/верхня межі)
|
||||
|
||||
Фрагментацію блоків реалізує `EmbeddedBlockChunker`:
|
||||
Фрагментація блоків реалізована в `EmbeddedBlockChunker`:
|
||||
|
||||
- **Нижня межа:** не видавати, доки буфер >= `minChars` (якщо не примусово).
|
||||
- **Верхня межа:** надавати перевагу розбиттю перед `maxChars`; якщо примусово, розбивати на `maxChars`.
|
||||
- **Бажаний розрив:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив.
|
||||
- **Огорожі коду:** ніколи не розбивати всередині огорож; під час примусового розбиття на `maxChars` закрити + знову відкрити огорожу, щоб Markdown залишався коректним.
|
||||
- **Верхня межа:** надавати перевагу розбиттю до `maxChars`; якщо примусово, розбивати на `maxChars`.
|
||||
- **Бажана точка розбиття:** `paragraph` → `newline` → `sentence` → `whitespace` → жорсткий розрив.
|
||||
- **Кодові блоки:** ніколи не розбивати всередині блоків; під час примусового розбиття на `maxChars` закрити + знову відкрити блок, щоб Markdown залишався коректним.
|
||||
|
||||
`maxChars` обмежується до `textChunkLimit` каналу, тому неможливо перевищити обмеження окремого каналу.
|
||||
`maxChars` обмежується до `textChunkLimit` каналу, тому перевищити обмеження конкретного каналу неможливо.
|
||||
|
||||
## Об’єднання (злиття потокових блоків)
|
||||
## Коалесценція (об’єднання потокових блоків)
|
||||
|
||||
Коли потокову передачу блоків увімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їх надсиланням. Це зменшує «спам з одного рядка», водночас зберігаючи поступовий вивід.
|
||||
Коли потокове передавання блоків увімкнено, OpenClaw може **об’єднувати послідовні блокові фрагменти** перед їхнім надсиланням. Це зменшує «спам одним рядком», водночас забезпечуючи поступовий вивід.
|
||||
|
||||
- Об’єднання чекає на **періоди простою** (`idleMs`) перед скиданням.
|
||||
- Коалесценція чекає на **паузи бездіяльності** (`idleMs`) перед скиданням.
|
||||
- Буфери обмежуються `maxChars` і будуть скинуті, якщо перевищать його.
|
||||
- `minChars` не дає надсилати крихітні фрагменти, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишковий текст).
|
||||
- З’єднувач виводиться з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл).
|
||||
- Перевизначення каналів доступні через `*.blockStreamingCoalesce` (зокрема конфігурації для окремих акаунтів).
|
||||
- Типове значення `minChars` для об’єднання підвищено до 1500 для Signal/Slack/Discord, якщо його не перевизначено.
|
||||
- `minChars` запобігає надсиланню крихітних фрагментів, доки не накопичиться достатньо тексту (фінальне скидання завжди надсилає залишковий текст).
|
||||
- З’єднувач визначається з `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → пробіл).
|
||||
- Перевизначення каналів доступні через `*.blockStreamingCoalesce` (включно з конфігураціями для окремих облікових записів).
|
||||
- Типове `minChars` для коалесценції підвищено до 1500 для Signal/Slack/Discord, якщо не перевизначено.
|
||||
|
||||
## Людський темп між блоками
|
||||
## Людиноподібний темп між блоками
|
||||
|
||||
Коли потокову передачу блоків увімкнено, можна додати **випадкову паузу** між блоковими відповідями (після першого блоку). Це робить відповіді з кількох бульбашок природнішими.
|
||||
Коли потокове передавання блоків увімкнено, можна додати **рандомізовану паузу** між блоковими відповідями (після першого блока). Це робить відповіді з кількох бульбашок природнішими.
|
||||
|
||||
- Конфігурація: `agents.defaults.humanDelay` (перевизначення для кожного агента через `agents.list[].humanDelay`).
|
||||
- Конфігурація: `agents.defaults.humanDelay` (перевизначається для кожного агента через `agents.list[].humanDelay`).
|
||||
- Режими: `off` (типово), `natural` (800–2500 мс), `custom` (`minMs`/`maxMs`).
|
||||
- Застосовується лише до **блокових відповідей**, а не до фінальних відповідей чи підсумків інструментів.
|
||||
- Застосовується лише до **блокових відповідей**, не до фінальних відповідей чи підсумків інструментів.
|
||||
|
||||
## "Передавати фрагменти чи все"
|
||||
## "Потоково передавати фрагменти або все"
|
||||
|
||||
Це відповідає:
|
||||
|
||||
- **Передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (видавати в міру генерації). Каналам, крім Telegram, також потрібне `*.blockStreaming: true`.
|
||||
- **Передати все наприкінці:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо кількома фрагментами, якщо дуже довго).
|
||||
- **Без потокової передачі блоків:** `blockStreamingDefault: "off"` (лише фінальна відповідь).
|
||||
- **Потоково передавати фрагменти:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (надсилати в міру генерації). Каналам не Telegram також потрібен `*.blockStreaming: true`.
|
||||
- **Потоково передати все наприкінці:** `blockStreamingBreak: "message_end"` (скинути один раз, можливо кількома фрагментами, якщо дуже довго).
|
||||
- **Без потокового передавання блоків:** `blockStreamingDefault: "off"` (лише фінальна відповідь).
|
||||
|
||||
**Примітка щодо каналів:** Потокова передача блоків **вимкнена, якщо**
|
||||
`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати потоком живий попередній перегляд (`channels.<channel>.streaming`) без блокових відповідей.
|
||||
**Примітка щодо каналів:** Потокове передавання блоків **вимкнено, якщо**
|
||||
`*.blockStreaming` явно не встановлено в `true`. Канали можуть передавати живий попередній перегляд
|
||||
(`channels.<channel>.streaming`) без блокових відповідей.
|
||||
|
||||
Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в `agents.defaults`, а не в кореневій конфігурації.
|
||||
Нагадування про розташування конфігурації: типові значення `blockStreaming*` містяться в
|
||||
`agents.defaults`, а не в кореневій конфігурації.
|
||||
|
||||
## Режими потокового попереднього перегляду
|
||||
## Режими потокового передавання попереднього перегляду
|
||||
|
||||
Канонічний ключ: `channels.<channel>.streaming`
|
||||
|
||||
Режими:
|
||||
|
||||
- `off`: вимкнути потоковий попередній перегляд.
|
||||
- `off`: вимкнути потокове передавання попереднього перегляду.
|
||||
- `partial`: один попередній перегляд, який замінюється найновішим текстом.
|
||||
- `block`: попередній перегляд оновлюється фрагментованими/доданими кроками.
|
||||
- `progress`: попередній перегляд прогресу/статусу під час генерації, фінальна відповідь після завершення.
|
||||
- `progress`: попередній перегляд прогресу/стану під час генерації, фінальна відповідь після завершення.
|
||||
|
||||
`streaming.mode: "block"` — це режим потокового передавання попереднього перегляду для каналів із можливістю редагування, таких як Discord і Telegram. Він не вмикає доставлення блоків у каналі там. Використовуйте `streaming.block.enabled` або застарілий ключ каналу `blockStreaming`, коли потрібні звичайні блокові відповіді. Microsoft Teams є винятком: у нього немає транспорту блоків чорнового попереднього перегляду, тому `streaming.mode: "block"` відображається на блокове доставлення Teams замість нативного часткового/прогресивного потокового передавання.
|
||||
|
||||
### Відповідність каналів
|
||||
|
||||
| Канал | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | --------------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | зіставляється з `partial` |
|
||||
| Discord | ✅ | ✅ | ✅ | зіставляється з `partial` |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| Канал | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | редагований чернетковий прогрес |
|
||||
| Discord | ✅ | ✅ | ✅ | редагований чернетковий прогрес |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | нативний потік прогресу |
|
||||
|
||||
Лише Slack:
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` перемикає нативні виклики Slack API для потокової передачі, коли `channels.slack.streaming.mode="partial"` (типово: `true`).
|
||||
- Нативна потокова передача Slack і статус треду асистента Slack потребують цільового треду відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі треду, але все одно можуть використовувати чернеткові дописи попереднього перегляду Slack і редагування.
|
||||
- `channels.slack.streaming.nativeTransport` перемикає виклики нативного API потокового передавання Slack, коли `channels.slack.streaming.mode="partial"` (типово: `true`).
|
||||
- Нативне потокове передавання Slack і статус потоку асистента Slack потребують цільового потоку відповіді. DM верхнього рівня не показують такий попередній перегляд у стилі потоку, але все одно можуть використовувати чернеткові дописи попереднього перегляду Slack і редагування.
|
||||
|
||||
Міграція застарілих ключів:
|
||||
|
||||
- Telegram: застарілі значення `streamMode` і скалярні/булеві значення `streaming` виявляються та мігруються шляхами сумісності doctor/config до `streaming.mode`.
|
||||
- Telegram: застарілий `streamMode` і скалярні/булеві значення `streaming` виявляються й мігруються шляхами doctor/сумісності конфігурації до `streaming.mode`.
|
||||
- Discord: `streamMode` + булевий `streaming` автоматично мігрують до enum `streaming`.
|
||||
- Slack: `streamMode` автоматично мігрує до `streaming.mode`; булевий `streaming` автоматично мігрує до `streaming.mode` плюс `streaming.nativeTransport`; застарілий `nativeStreaming` автоматично мігрує до `streaming.nativeTransport`.
|
||||
|
||||
@ -143,50 +148,50 @@ Model output
|
||||
|
||||
Telegram:
|
||||
|
||||
- Використовує `sendMessage` + оновлення попереднього перегляду через `editMessageText` у DM і групах/темах.
|
||||
- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий приблизно одну хвилину, а потім очищає попередній перегляд, щоб мітка часу Telegram відображала завершення відповіді.
|
||||
- Потоковий попередній перегляд пропускається, коли потокову передачу блоків Telegram явно увімкнено (щоб уникнути подвійної потокової передачі).
|
||||
- Використовує `sendMessage` + `editMessageText` для оновлень попереднього перегляду в DM і групах/темах.
|
||||
- Надсилає нове фінальне повідомлення замість редагування на місці, коли попередній перегляд був видимий приблизно одну хвилину, а потім очищає попередній перегляд, щоб позначка часу Telegram відображала завершення відповіді.
|
||||
- Потокове передавання попереднього перегляду пропускається, коли потокове передавання блоків Telegram явно ввімкнено (щоб уникнути подвійного потокового передавання).
|
||||
- `/reasoning stream` може записувати міркування в попередній перегляд.
|
||||
|
||||
Discord:
|
||||
|
||||
- Використовує надсилання + редагування повідомлень попереднього перегляду.
|
||||
- Режим `block` використовує фрагментацію чернетки (`draftChunk`).
|
||||
- Потоковий попередній перегляд пропускається, коли потокову передачу блоків Discord явно увімкнено.
|
||||
- Фінальні медіа, помилки та навантаження з явною відповіддю скасовують очікувані попередні перегляди без скидання нової чернетки, а потім використовують звичайну доставку.
|
||||
- Режим `block` використовує чернеткову фрагментацію (`draftChunk`).
|
||||
- Потокове передавання попереднього перегляду пропускається, коли потокове передавання блоків Discord явно ввімкнено.
|
||||
- Фінальні медіа, помилки й корисні навантаження явної відповіді скасовують очікувані попередні перегляди без скидання нового чернеткового повідомлення, а потім використовують звичайне доставлення.
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` може використовувати нативну потокову передачу Slack (`chat.startStream`/`append`/`stop`), коли вона доступна.
|
||||
- `block` використовує чернеткові попередні перегляди у стилі додавання.
|
||||
- `progress` використовує текст попереднього перегляду статусу, потім фінальну відповідь.
|
||||
- DM верхнього рівня без треду відповіді використовують чернеткові дописи попереднього перегляду та редагування замість нативної потокової передачі Slack.
|
||||
- Нативний і чернетковий потоковий попередній перегляд пригнічують блокові відповіді для цього ходу, тому відповідь Slack передається потоком лише одним шляхом доставки.
|
||||
- Фінальні медіа/помилки та фінали прогресу не створюють одноразових чернеткових повідомлень; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний чернетковий текст.
|
||||
- `partial` може використовувати нативне потокове передавання Slack (`chat.startStream`/`append`/`stop`), коли доступно.
|
||||
- `block` використовує чернеткові попередні перегляди в стилі додавання.
|
||||
- `progress` використовує текст попереднього перегляду стану, а потім фінальну відповідь.
|
||||
- DM верхнього рівня без потоку відповіді використовують чернеткові дописи попереднього перегляду та редагування замість нативного потокового передавання Slack.
|
||||
- Нативне й чернеткове потокове передавання попереднього перегляду пригнічує блокові відповіді для цього ходу, тому відповідь Slack передається потоком лише одним шляхом доставлення.
|
||||
- Фінальні корисні навантаження медіа/помилок і фінали прогресу не створюють одноразові чернеткові повідомлення; лише текстові/блокові фінали, які можуть редагувати попередній перегляд, скидають очікуваний чернетковий текст.
|
||||
|
||||
Mattermost:
|
||||
|
||||
- Передає думки, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надіслати.
|
||||
- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний на момент фіналізації.
|
||||
- Фінальні медіа/помилки скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою замість скидання тимчасового допису попереднього перегляду.
|
||||
- Передає мислення, активність інструментів і частковий текст відповіді в один чернетковий допис попереднього перегляду, який фіналізується на місці, коли фінальну відповідь безпечно надсилати.
|
||||
- Повертається до надсилання нового фінального допису, якщо допис попереднього перегляду було видалено або він інакше недоступний під час фіналізації.
|
||||
- Фінальні корисні навантаження медіа/помилок скасовують очікувані оновлення попереднього перегляду перед звичайним доставленням замість скидання тимчасового допису попереднього перегляду.
|
||||
|
||||
Matrix:
|
||||
|
||||
- Чернеткові попередні перегляди фіналізуються на місці, коли фінальний текст може повторно використати подію попереднього перегляду.
|
||||
- Фінали лише з медіа, помилками та з невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайною доставкою; уже видимий застарілий попередній перегляд редагується як видалений.
|
||||
- Фінали лише з медіа, помилками й невідповідністю цілі відповіді скасовують очікувані оновлення попереднього перегляду перед звичайним доставленням; уже видимий застарілий попередній перегляд редагується.
|
||||
|
||||
### Оновлення попереднього перегляду прогресу інструментів
|
||||
|
||||
Потоковий попередній перегляд також може включати оновлення **прогресу інструментів** — короткі рядки статусу на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента", які з’являються в тому самому повідомленні попереднього перегляду, доки інструменти працюють, перед фінальною відповіддю. Це підтримує візуальну активність багатоетапних ходів з інструментами, а не тишу між першим попереднім переглядом думок і фінальною відповіддю.
|
||||
Потокове передавання попереднього перегляду також може містити оновлення **прогресу інструментів** — короткі рядки стану на кшталт "пошук в інтернеті", "читання файлу" або "виклик інструмента", — які з’являються в тому самому повідомленні попереднього перегляду, поки інструменти працюють, до фінальної відповіді. Це зберігає багатокрокові ходи з інструментами візуально активними, а не мовчазними між першим попереднім переглядом мислення та фінальною відповіддю.
|
||||
|
||||
Підтримувані поверхні:
|
||||
|
||||
- **Discord**, **Slack**, **Telegram** і **Matrix** типово передають прогрес інструментів у редагування живого попереднього перегляду, коли потоковий попередній перегляд активний.
|
||||
- **Discord**, **Slack**, **Telegram** і **Matrix** типово передають прогрес інструментів у редагування живого попереднього перегляду, коли потокове передавання попереднього перегляду активне. Microsoft Teams використовує свій нативний потік прогресу в особистих чатах.
|
||||
- Telegram постачається з увімкненими оновленнями попереднього перегляду прогресу інструментів із `v2026.4.22`; збереження їх увімкненими підтримує цю випущену поведінку.
|
||||
- **Mattermost** уже включає активність інструментів у свій єдиний чернетковий допис попереднього перегляду (див. вище).
|
||||
- Редагування прогресу інструментів дотримуються активного режиму потокового попереднього перегляду; вони пропускаються, коли потоковий попередній перегляд має значення `off` або коли потокова передача блоків перебрала повідомлення. У Telegram `streaming.mode: "off"` означає лише фінальну відповідь: загальні повідомлення про прогрес також пригнічуються замість доставки як окремі повідомлення "Працюємо...", тоді як запити підтвердження, медіанавантаження та помилки все одно маршрутизуються звичайно.
|
||||
- Щоб зберегти потоковий попередній перегляд, але приховати рядки прогресу інструментів, установіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, установіть `streaming.mode` у `off`.
|
||||
- Вибрані відповіді з цитатою Telegram є винятком: коли `replyToMode` не дорівнює `"off"` і наявний текст вибраної цитати, OpenClaw пропускає потік попереднього перегляду відповіді для цього ходу, тому рядки попереднього перегляду прогресу інструментів не можуть відобразитися. Відповіді на поточне повідомлення без тексту вибраної цитати все одно зберігають потоковий попередній перегляд. Докладніше див. у [документації каналу Telegram](/uk/channels/telegram).
|
||||
- Редагування прогресу інструментів дотримуються активного режиму потокового передавання попереднього перегляду; вони пропускаються, коли потокове передавання попереднього перегляду `off` або коли потокове передавання блоків узяло повідомлення на себе. У Telegram `streaming.mode: "off"` означає лише фінал: загальні повідомлення про прогрес також пригнічуються замість доставлення як окремі повідомлення стану, тоді як запити на схвалення, медіакорисні навантаження й помилки все одно маршрутизуються звичайно.
|
||||
- Щоб зберегти потокове передавання попереднього перегляду, але приховати рядки прогресу інструментів, встановіть `streaming.preview.toolProgress` у `false` для цього каналу. Щоб повністю вимкнути редагування попереднього перегляду, встановіть `streaming.mode` у `off`.
|
||||
- Вибрані цитовані відповіді Telegram є винятком: коли `replyToMode` не `"off"` і присутній вибраний текст цитати, OpenClaw пропускає потік попереднього перегляду відповіді для цього ходу, тому рядки попереднього перегляду прогресу інструментів не можуть відобразитися. Відповіді на поточне повідомлення без вибраного тексту цитати все одно зберігають потокове передавання попереднього перегляду. Докладніше див. у [документації каналу Telegram](/uk/channels/telegram).
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -207,6 +212,7 @@ Matrix:
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Повідомлення](/uk/concepts/messages) — життєвий цикл повідомлень і доставка
|
||||
- [Повторна спроба](/uk/concepts/retry) — поведінка повторної спроби в разі помилки доставки
|
||||
- [Канали](/uk/channels) — підтримка потокової передачі для кожного каналу
|
||||
- [Чернетки прогресу](/uk/concepts/progress-drafts) — видимі повідомлення про роботу в процесі, що оновлюються під час довгих ходів
|
||||
- [Повідомлення](/uk/concepts/messages) — життєвий цикл і доставлення повідомлень
|
||||
- [Повторна спроба](/uk/concepts/retry) — поведінка повторної спроби після помилки доставлення
|
||||
- [Канали](/uk/channels) — підтримка потокового передавання для кожного каналу
|
||||
|
||||
@ -1,56 +1,56 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування Plugin каналу (автентифікація, контроль доступу, кілька облікових записів)
|
||||
- Усунення несправностей із ключами конфігурації для кожного каналу
|
||||
- Аудит політики особистих повідомлень, групової політики або контролю згадувань
|
||||
summary: 'Налаштування каналів: контроль доступу, сполучення, ключі для кожного каналу в Slack, Discord, Telegram, WhatsApp, Matrix, iMessage тощо'
|
||||
- Усунення неполадок із ключами конфігурації для окремих каналів
|
||||
- Аудит політики особистих повідомлень, групової політики або обмеження згадок
|
||||
summary: 'Конфігурація каналів: контроль доступу, сполучення та ключі для кожного каналу в Slack, Discord, Telegram, WhatsApp, Matrix, iMessage тощо'
|
||||
title: Конфігурація — канали
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T18:20:39Z"
|
||||
generated_at: "2026-05-03T21:06:17Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b92d7fe63a3d27c1740abb0986d6641d14d8d1017051f1744a02e1db77fda3c8
|
||||
source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c
|
||||
source_path: gateway/config-channels.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Ключі конфігурації для кожного каналу в `channels.*`. Охоплює доступ до DM і груп,
|
||||
налаштування кількох облікових записів, обмеження за згадкою та ключі для окремих каналів Slack, Discord,
|
||||
Telegram, WhatsApp, Matrix, iMessage та інших вбудованих plugins каналів.
|
||||
Поканальні ключі конфігурації в `channels.*`. Охоплює доступ до DM і груп,
|
||||
налаштування з кількома обліковими записами, керування згадками та поканальні ключі для Slack, Discord,
|
||||
Telegram, WhatsApp, Matrix, iMessage та інших вбудованих Plugin каналів.
|
||||
|
||||
Для агентів, інструментів, середовища виконання gateway та інших ключів верхнього рівня див.
|
||||
[довідник конфігурації](/uk/gateway/configuration-reference).
|
||||
[Довідник конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
## Канали
|
||||
|
||||
Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не встановлено `enabled: false`).
|
||||
Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`).
|
||||
|
||||
### Доступ до DM і груп
|
||||
|
||||
Усі канали підтримують політики DM і політики груп:
|
||||
Усі канали підтримують політики DM і груп:
|
||||
|
||||
| Політика DM | Поведінка |
|
||||
| Політика DM | Поведінка |
|
||||
| ------------------- | --------------------------------------------------------------- |
|
||||
| `pairing` (за замовчуванням) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити |
|
||||
| `allowlist` | Лише відправники в `allowFrom` (або в сховищі дозволених після сполучення) |
|
||||
| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) |
|
||||
| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити |
|
||||
| `allowlist` | Лише відправники в `allowFrom` (або в парному allow-сховищі) |
|
||||
| `open` | Дозволити всі вхідні DM (потребує `allowFrom: ["*"]`) |
|
||||
| `disabled` | Ігнорувати всі вхідні DM |
|
||||
|
||||
| Політика груп | Поведінка |
|
||||
| -------------------- | ----------------------------------------------------- |
|
||||
| `allowlist` (за замовчуванням) | Лише групи, що відповідають налаштованому списку дозволених |
|
||||
| `open` | Обходити списки дозволених для груп (обмеження за згадкою все одно застосовується) |
|
||||
| `disabled` | Блокувати всі повідомлення груп/кімнат |
|
||||
| Політика груп | Поведінка |
|
||||
| --------------------- | ------------------------------------------------------ |
|
||||
| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist |
|
||||
| `open` | Обійти групові allowlist (керування згадками все ще діє) |
|
||||
| `disabled` | Блокувати всі повідомлення груп/кімнат |
|
||||
|
||||
<Note>
|
||||
`channels.defaults.groupPolicy` задає стандартне значення, коли `groupPolicy` провайдера не встановлено.
|
||||
Коди сполучення спливають через 1 годину. Очікувані запити на сполучення DM обмежені **3 на канал**.
|
||||
`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` провайдера не встановлено.
|
||||
Коди сполучення спливають через 1 годину. Очікувані запити на сполучення DM обмежено **3 на канал**.
|
||||
Якщо блок провайдера повністю відсутній (`channels.<provider>` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску.
|
||||
</Note>
|
||||
|
||||
### Перевизначення моделі каналу
|
||||
|
||||
Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Зіставлення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, заданого через `/model`).
|
||||
Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Зіставлення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, установленого через `/model`).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -71,7 +71,7 @@ Telegram, WhatsApp, Matrix, iMessage та інших вбудованих plugin
|
||||
}
|
||||
```
|
||||
|
||||
### Стандартні значення каналів і Heartbeat
|
||||
### Типові значення каналів і Heartbeat
|
||||
|
||||
Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat між провайдерами:
|
||||
|
||||
@ -92,14 +92,14 @@ Telegram, WhatsApp, Matrix, iMessage та інших вбудованих plugin
|
||||
```
|
||||
|
||||
- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено.
|
||||
- `channels.defaults.contextVisibility`: стандартний режим видимості додаткового контексту для всіх каналів. Значення: `all` (за замовчуванням, включає весь цитований/тредовий/історичний контекст), `allowlist` (включає лише контекст від відправників зі списку дозволених), `allowlist_quote` (так само, як allowlist, але зберігає явний контекст цитати/відповіді). Перевизначення для каналу: `channels.<channel>.contextVisibility`.
|
||||
- `channels.defaults.heartbeat.showOk`: включати справні статуси каналів у вивід heartbeat.
|
||||
- `channels.defaults.heartbeat.showAlerts`: включати статуси погіршення/помилки у вивід heartbeat.
|
||||
- `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід heartbeat у стилі індикатора.
|
||||
- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/тредів/історії), `allowlist` (включати контекст лише від відправників з allowlist), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Поканальне перевизначення: `channels.<channel>.contextVisibility`.
|
||||
- `channels.defaults.heartbeat.showOk`: включати справні статуси каналів у вивід Heartbeat.
|
||||
- `channels.defaults.heartbeat.showAlerts`: включати погіршені/помилкові статуси у вивід Heartbeat.
|
||||
- `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикаторів.
|
||||
|
||||
### WhatsApp
|
||||
|
||||
WhatsApp працює через web-канал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс.
|
||||
WhatsApp працює через вебканал gateway (Baileys Web). Він запускається автоматично, коли існує зв’язаний сеанс.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -137,7 +137,7 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Multi-account WhatsApp">
|
||||
<Accordion title="WhatsApp із кількома обліковими записами">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -155,10 +155,10 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
- Вихідні команди за замовчуванням використовують обліковий запис `default`, якщо він є; інакше перший налаштований id облікового запису (після сортування).
|
||||
- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір стандартного облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше перший налаштований ID облікового запису (відсортовано).
|
||||
- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, коли він збігається з ID налаштованого облікового запису.
|
||||
- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`.
|
||||
- Перевизначення для облікового запису: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
|
||||
- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -217,14 +217,14 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для стандартного облікового запису.
|
||||
- `apiRoot` — це лише корінь Telegram Bot API. Використовуйте `https://api.telegram.org` або власний self-hosted/proxy-корінь, а не `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` видаляє випадковий кінцевий суфікс `/bot<TOKEN>`.
|
||||
- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір стандартного облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- У налаштуваннях із кількома обліковими записами (2+ id облікових записів) задайте явний стандартний обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, коли він відсутній або недійсний.
|
||||
- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), з `TELEGRAM_BOT_TOKEN` як резервом для типового облікового запису.
|
||||
- `apiRoot` — це лише корінь Telegram Bot API. Використовуйте `https://api.telegram.org` або власний self-hosted/proxy корінь, а не `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` видаляє випадковий кінцевий суфікс `/bot<TOKEN>`.
|
||||
- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ID налаштованого облікового запису.
|
||||
- У налаштуваннях із кількома обліковими записами (2+ ID облікових записів) задайте явний типовий (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, коли він відсутній або недійсний.
|
||||
- `configWrites: false` блокує ініційовані Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`).
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна в [агентах ACP](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантику полів спільно описано в [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- Попередні перегляди потоків Telegram використовують `sendMessage` + `editMessageText` (працює в прямих і групових чатах).
|
||||
- Політика повторних спроб: див. [політику повторних спроб](/uk/concepts/retry).
|
||||
- Політика повторів: див. [Політика повторів](/uk/concepts/retry).
|
||||
|
||||
### Discord
|
||||
|
||||
@ -279,7 +279,7 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
historyLimit: 20,
|
||||
textChunkLimit: 2000,
|
||||
chunkMode: "length", // length | newline
|
||||
streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
|
||||
streaming: "off", // off | partial | block | progress
|
||||
maxLinesPerMessage: 17,
|
||||
ui: {
|
||||
components: {
|
||||
@ -329,41 +329,41 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису.
|
||||
- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; параметри повторних спроб/політики облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання.
|
||||
- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- Використовуйте `user:<id>` (DM) або `channel:<id>` (канал гільдії) для цілей доставки; прості числові ID відхиляються.
|
||||
- Слаги гільдій пишуться малими літерами, а пробіли замінюються на `-`; ключі каналів використовують назву у вигляді слага (без `#`). Надавайте перевагу ID гільдій.
|
||||
- Повідомлення, створені ботами, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно відфільтровуються).
|
||||
- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервом для стандартного облікового запису.
|
||||
- Прямі вихідні виклики, що надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політики облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання.
|
||||
- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір стандартного облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- Використовуйте `user:<id>` (DM) або `channel:<id>` (канал гільдії) для цілей доставки; голі числові ID відхиляються.
|
||||
- Слаґи гільдій мають нижній регістр із пробілами, заміненими на `-`; ключі каналів використовують ім’я зі слаґом (без `#`). Віддавайте перевагу ID гільдій.
|
||||
- Повідомлення, створені ботами, за замовчуванням ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються).
|
||||
- `channels.discord.guilds.<id>.ignoreOtherMentions` (і перевизначення каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here).
|
||||
- `channels.discord.mentionAliases` відображає стабільний вихідний текст `@handle` на Discord ID користувачів перед надсиланням, щоб відомих учасників команди можна було згадувати детерміновано, навіть коли тимчасовий кеш каталогу порожній. Перевизначення для окремих облікових записів розміщуються в `channels.discord.accounts.<accountId>.mentionAliases`.
|
||||
- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони мають менше ніж 2000 символів.
|
||||
- `channels.discord.mentionAliases` зіставляє стабільний вихідний текст `@handle` з ID користувачів Discord перед надсиланням, щоб відомих учасників команди можна було згадувати детерміновано навіть коли тимчасовий кеш каталогу порожній. Перевизначення для окремих облікових записів розміщуються в `channels.discord.accounts.<accountId>.mentionAliases`.
|
||||
- `maxLinesPerMessage` (стандартно 17) розбиває високі повідомлення навіть коли вони мають менше ніж 2000 символів.
|
||||
- `channels.discord.threadBindings` керує маршрутизацією Discord, прив’язаною до гілок:
|
||||
- `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація)
|
||||
- `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація)
|
||||
- `idleHours`: перевизначення Discord для автоматичного скасування фокуса через неактивність у годинах (`0` вимикає)
|
||||
- `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає)
|
||||
- `spawnSessions`: перемикач для `sessions_spawn({ thread: true })` і автоматичного створення/прив’язування гілок ACP thread-spawn (типово: `true`)
|
||||
- `defaultSpawnContext`: нативний контекст підагента для запусків, прив’язаних до гілок (типово `"fork"`)
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна в [ACP Agents](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2.
|
||||
- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення авто-приєднання + LLM + TTS. Текстові конфігурації Discord типово залишають голос вимкненим; установіть `channels.discord.voice.enabled=true`, щоб увімкнути.
|
||||
- `spawnSessions`: перемикач для `sessions_spawn({ thread: true })` і автоматичного створення/прив’язування гілок для ACP thread-spawn (стандартно: `true`)
|
||||
- `defaultSpawnContext`: нативний контекст субагента для запусків, прив’язаних до гілки (стандартно `"fork"`)
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна в [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів компонентів Discord v2.
|
||||
- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення автоприєднання + LLM + TTS. Конфігурації Discord лише для тексту за замовчуванням залишають голос вимкненим; установіть `channels.discord.voice.enabled=true`, щоб увімкнути.
|
||||
- `channels.discord.voice.model` необов’язково перевизначає модель LLM, що використовується для відповідей у голосових каналах Discord.
|
||||
- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` передаються до параметрів DAVE `@discordjs/voice` (типово `true` і `24`).
|
||||
- `channels.discord.voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб авто-приєднання (типово `30000`).
|
||||
- `channels.discord.voice.reconnectGraceMs` керує тим, скільки часу від’єднана голосова сесія може входити в сигналізацію повторного підключення, перш ніж OpenClaw її знищить (типово `15000`).
|
||||
- OpenClaw додатково намагається відновити приймання голосу, залишаючи голосову сесію та приєднуючись до неї знову після повторних помилок розшифрування.
|
||||
- `channels.discord.streaming` є канонічним ключем режиму потоку. Застарілі значення `streamMode` і булеві `streaming` мігруються автоматично.
|
||||
- `channels.discord.autoPresence` відображає доступність середовища виконання на присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу.
|
||||
- `channels.discord.dangerouslyAllowNameMatching` знову вмикає змінне зіставлення імен/тегів (режим сумісності break-glass).
|
||||
- `channels.discord.execApprovals`: нативна для Discord доставка підтверджень exec і авторизація затверджувачів.
|
||||
- `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі підтвердження exec активуються, коли затверджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
|
||||
- `approvers`: Discord ID користувачів, яким дозволено затверджувати запити exec. Якщо пропущено, використовується `commands.ownerAllowFrom`.
|
||||
- `agentFilter`: необов’язковий список дозволених ID агентів. Пропустіть, щоб пересилати підтвердження для всіх агентів.
|
||||
- `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або регулярний вираз).
|
||||
- `target`: куди надсилати запити на підтвердження. `"dm"` (типово) надсилає в DM затверджувачам, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли ціль містить `"channel"`, кнопки можуть використовувати лише визначені затверджувачі.
|
||||
- `cleanupAfterResolve`: коли `true`, видаляє DM із підтвердженнями після затвердження, відмови або тайм-ауту.
|
||||
- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` передаються до параметрів DAVE `@discordjs/voice` (стандартно `true` і `24`).
|
||||
- `channels.discord.voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб автоприєднання (стандартно `30000`).
|
||||
- `channels.discord.voice.reconnectGraceMs` керує тим, скільки часу від’єднаний голосовий сеанс може входити в сигналізацію перепідключення, перш ніж OpenClaw його знищить (стандартно `15000`).
|
||||
- OpenClaw додатково намагається відновити приймання голосу, виходячи з голосового сеансу та повторно приєднуючись до нього після повторних помилок розшифрування.
|
||||
- `channels.discord.streaming` є канонічним ключем режиму потоку. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються.
|
||||
- `channels.discord.autoPresence` зіставляє доступність середовища виконання з присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дає змогу необов’язково перевизначати текст статусу.
|
||||
- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає змінне зіставлення імен/тегів (режим сумісності break-glass).
|
||||
- `channels.discord.execApprovals`: нативна для Discord доставка підтверджень exec і авторизація схвалювачів.
|
||||
- `enabled`: `true`, `false` або `"auto"` (стандартно). В автоматичному режимі підтвердження exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
|
||||
- `approvers`: ID користувачів Discord, яким дозволено схвалювати запити exec. Якщо пропущено, використовується резерв `commands.ownerAllowFrom`.
|
||||
- `agentFilter`: необов’язковий allowlist ID агентів. Пропустіть, щоб пересилати підтвердження для всіх агентів.
|
||||
- `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
|
||||
- `target`: куди надсилати запити підтвердження. `"dm"` (стандартно) надсилає в DM схвалювачів, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли ціль містить `"channel"`, кнопки можуть використовувати лише визначені схвалювачі.
|
||||
- `cleanupAfterResolve`: коли `true`, видаляє DM підтвердження після схвалення, відмови або тайм-ауту.
|
||||
|
||||
**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (з `guilds.<id>.users` для всіх повідомлень).
|
||||
**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, стандартно), `all` (усі повідомлення), `allowlist` (з `guilds.<id>.users` для всіх повідомлень).
|
||||
|
||||
### Google Chat
|
||||
|
||||
@ -394,11 +394,11 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`).
|
||||
- SecretRef облікового запису служби також підтримується (`serviceAccountRef`).
|
||||
- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
|
||||
- JSON сервісного облікового запису: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`).
|
||||
- SecretRef сервісного облікового запису також підтримується (`serviceAccountRef`).
|
||||
- Резерви env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
|
||||
- Використовуйте `spaces/<spaceId>` або `users/<userId>` для цілей доставки.
|
||||
- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає змінне зіставлення email principal (режим сумісності break-glass).
|
||||
- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає змінне зіставлення email-принципала (режим сумісності break-glass).
|
||||
|
||||
### Slack
|
||||
|
||||
@ -470,44 +470,44 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з
|
||||
}
|
||||
```
|
||||
|
||||
- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта змінних середовища типового облікового запису).
|
||||
- **HTTP mode** потребує `botToken` плюс `signingSecret` (на кореневому рівні або для окремого облікового запису).
|
||||
- `socketMode` передає налаштування транспорту Slack SDK Socket Mode до публічного API приймача Bolt. Використовуйте це лише під час розслідування тайм-аутів ping/pong або застарілої поведінки websocket.
|
||||
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають plaintext
|
||||
- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резерву env стандартного облікового запису).
|
||||
- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису).
|
||||
- `socketMode` передає налаштування транспорту Slack SDK Socket Mode до публічного API приймача Bolt. Використовуйте це лише під час розслідування тайм-аутів ping/pong або поведінки застарілого websocket.
|
||||
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті текстові
|
||||
рядки або об’єкти SecretRef.
|
||||
- Знімки облікових записів Slack надають поля джерела/статусу для окремих облікових даних, як-от
|
||||
`botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode —
|
||||
- Знімки облікових записів Slack показують поля джерела/стану для окремих облікових даних, як-от
|
||||
`botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode,
|
||||
`signingSecretStatus`. `configured_unavailable` означає, що обліковий запис
|
||||
налаштовано через SecretRef, але поточний шлях команди/середовища виконання не зміг
|
||||
налаштований через SecretRef, але поточний шлях команди/середовища виконання не зміг
|
||||
визначити значення секрету.
|
||||
- `configWrites: false` блокує записи конфігурації, ініційовані Slack.
|
||||
- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- `channels.slack.streaming.mode` є канонічним ключем режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві `streaming` і `nativeStreaming` мігруються автоматично.
|
||||
- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір стандартного облікового запису, коли він збігається з налаштованим id облікового запису.
|
||||
- `channels.slack.streaming.mode` є канонічним ключем режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві `streaming` і `nativeStreaming` автоматично мігруються.
|
||||
- Використовуйте `user:<id>` (DM) або `channel:<id>` для цілей доставки.
|
||||
|
||||
**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`).
|
||||
**Режими сповіщень про реакції:** `off`, `own` (стандартно), `all`, `allowlist` (з `reactionAllowlist`).
|
||||
|
||||
**Ізоляція сесії гілки:** `thread.historyScope` є окремим для кожної гілки (типово) або спільним для всього каналу. `thread.inheritParent` копіює транскрипт батьківського каналу до нових гілок.
|
||||
**Ізоляція сеансів гілок:** `thread.historyScope` є окремою для кожної гілки (стандартно) або спільною для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові гілки.
|
||||
|
||||
- Нативний streaming Slack разом зі статусом гілки в стилі Slack assistant "is typing..." потребують цілі гілки для відповіді. DM верхнього рівня типово залишаються поза гілками, тому вони все ще можуть транслюватися через чорнові попередні перегляди Slack із публікацією та редагуванням замість показу нативного потокового/статусного попереднього перегляду в стилі гілки.
|
||||
- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте шорткод емодзі Slack, наприклад `"hourglass_flowing_sand"`.
|
||||
- `channels.slack.execApprovals`: нативна для Slack доставка підтверджень exec і авторизація затверджувачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack ID користувачів), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
|
||||
- Нативне потокове передавання Slack разом зі статусом гілки в стилі асистента Slack "is typing..." потребують цілі гілки відповіді. DM верхнього рівня за замовчуванням залишаються поза гілками, тож вони все ще можуть потоково передаватися через чернеткові попередні перегляди Slack із публікацією та редагуванням замість показу нативного потокового/статусного попереднього перегляду в стилі гілки.
|
||||
- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім прибирає її після завершення. Використовуйте шорткод emoji Slack, наприклад `"hourglass_flowing_sand"`.
|
||||
- `channels.slack.execApprovals`: нативна для Slack доставка підтверджень exec і авторизація схвалювачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
|
||||
|
||||
| Група дій | Типово | Примітки |
|
||||
| Група дій | Стандартно | Примітки |
|
||||
| ------------ | ------- | ---------------------- |
|
||||
| reactions | увімкнено | Реагувати + перелічувати реакції |
|
||||
| messages | увімкнено | Читати/надсилати/редагувати/видаляти |
|
||||
| pins | увімкнено | Закріпити/відкріпити/перелічити |
|
||||
| memberInfo | увімкнено | Інформація про учасника |
|
||||
| emojiList | увімкнено | Список користувацьких емодзі |
|
||||
| emojiList | увімкнено | Список власних emoji |
|
||||
|
||||
### Mattermost
|
||||
|
||||
Mattermost постачається як bundled Plugin у поточних випусках OpenClaw. Старіші або
|
||||
кастомні збірки можуть встановити поточний npm-пакет за допомогою
|
||||
Mattermost постачається як вбудований Plugin у поточних випусках OpenClaw. Старіші або
|
||||
кастомні збірки можуть установити поточний npm-пакет за допомогою
|
||||
`openclaw plugins install @openclaw/mattermost`. Перевірте
|
||||
[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost)
|
||||
для поточних dist-tags перед фіксацією версії.
|
||||
щодо поточних dist-tags перед закріпленням версії.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -537,22 +537,22 @@ Mattermost постачається як bundled Plugin у поточних ви
|
||||
}
|
||||
```
|
||||
|
||||
Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера).
|
||||
Режими чату: `oncall` (відповідати на @-згадку, стандартно), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера).
|
||||
|
||||
Коли нативні команди Mattermost увімкнено:
|
||||
|
||||
- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою.
|
||||
- `commands.callbackUrl` має розв’язуватися в кінцеву точку Gateway OpenClaw і бути доступним із сервера Mattermost.
|
||||
- Нативні slash callbacks автентифікуються токенами для кожної команди, які повертає
|
||||
Mattermost під час реєстрації slash command. Якщо реєстрація завершується невдало або жодні
|
||||
команди не активовано, OpenClaw відхиляє callbacks із повідомленням
|
||||
- `commands.callbackUrl` має вказувати на кінцеву точку Gateway OpenClaw і бути доступним із сервера Mattermost.
|
||||
- Нативні slash-callbacks автентифікуються токенами для кожної команди, які повертає
|
||||
Mattermost під час реєстрації slash-команди. Якщо реєстрація завершується помилкою або
|
||||
жодні команди не активовано, OpenClaw відхиляє callbacks з
|
||||
`Unauthorized: invalid command token.`
|
||||
- Для приватних/tailnet/внутрішніх хостів callback Mattermost може вимагати,
|
||||
щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback.
|
||||
- Для приватних/tailnet/внутрішніх хостів callback Mattermost може вимагати, щоб
|
||||
`ServiceSettings.AllowedUntrustedInternalConnections` містив callback-хост/домен.
|
||||
Використовуйте значення хоста/домену, а не повні URL-адреси.
|
||||
- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані Mattermost записи конфігурації.
|
||||
- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах.
|
||||
- `channels.mattermost.groups.<channelId>.requireMention`: перевизначення mention-gating для окремого каналу (`"*"` для типового значення).
|
||||
- `channels.mattermost.groups.<channelId>.requireMention`: перевизначення mention-gating для кожного каналу (`"*"` для типового значення).
|
||||
- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису.
|
||||
|
||||
### Signal
|
||||
@ -582,7 +582,7 @@ Mattermost постачається як bundled Plugin у поточних ви
|
||||
|
||||
### BlueBubbles
|
||||
|
||||
BlueBubbles — рекомендований шлях iMessage (підтримується Plugin, налаштовується в `channels.bluebubbles`).
|
||||
BlueBubbles — рекомендований шлях для iMessage (на основі Plugin, налаштовується в `channels.bluebubbles`).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -599,7 +599,7 @@ BlueBubbles — рекомендований шлях iMessage (підтриму
|
||||
|
||||
- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
|
||||
- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису.
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сеансів ACP. Використовуйте handle BlueBubbles або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [ACP Agents](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сеансів ACP. Використовуйте handle BlueBubbles або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles).
|
||||
|
||||
### iMessage
|
||||
@ -634,9 +634,9 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а
|
||||
- Надавайте перевагу цілям `chat_id:<id>`. Використовуйте `imsg chats --limit 20`, щоб перелічити чати.
|
||||
- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
|
||||
- `attachmentRoots` і `remoteAttachmentRoots` обмежують вхідні шляхи вкладень (типово: `/Users/*/Library/Messages/Attachments`).
|
||||
- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста relay уже є в `~/.ssh/known_hosts`.
|
||||
- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста ретранслятора вже є в `~/.ssh/known_hosts`.
|
||||
- `channels.imessage.configWrites`: дозволити або заборонити ініційовані iMessage записи конфігурації.
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сеансів ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [ACP Agents](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сеансів ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings).
|
||||
|
||||
<Accordion title="Приклад SSH-обгортки iMessage">
|
||||
|
||||
@ -649,7 +649,7 @@ exec ssh -T gateway-host imsg "$@"
|
||||
|
||||
### Matrix
|
||||
|
||||
Matrix підтримується Plugin і налаштовується в `channels.matrix`.
|
||||
Matrix працює на основі Plugin і налаштовується в `channels.matrix`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -679,25 +679,25 @@ Matrix підтримується Plugin і налаштовується в `cha
|
||||
}
|
||||
```
|
||||
|
||||
- Автентифікація за токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`.
|
||||
- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts.<id>.proxy`.
|
||||
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і ця згода на мережу є незалежними елементами керування.
|
||||
- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у налаштуваннях із кількома обліковими записами.
|
||||
- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`.
|
||||
- `channels.matrix.execApprovals`: нативна для Matrix доставка схвалень exec і авторизація затверджувача.
|
||||
- `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли затверджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
|
||||
- `approvers`: ідентифікатори користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати запити exec.
|
||||
- `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Пропустіть, щоб пересилати схвалення для всіх агентів.
|
||||
- `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або регулярний вираз).
|
||||
- `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`.
|
||||
- Перевизначення для окремих облікових записів: `channels.matrix.accounts.<id>.execApprovals`.
|
||||
- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сеанси: `per-user` (типово) спільно використовується за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату.
|
||||
- Перевірки стану Matrix і live-пошуки каталогу використовують ту саму політику проксі, що й трафік під час виконання.
|
||||
- Автентифікація через токен використовує `accessToken`; автентифікація паролем використовує `userId` + `password`.
|
||||
- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його за допомогою `channels.matrix.accounts.<id>.proxy`.
|
||||
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і цей мережевий opt-in є незалежними елементами керування.
|
||||
- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами.
|
||||
- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові DM-подібні запрошення ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`.
|
||||
- `channels.matrix.execApprovals`: нативна для Matrix доставка підтверджень exec і авторизація approver.
|
||||
- `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі підтвердження exec активуються, коли approver можна визначити з `approvers` або `commands.ownerAllowFrom`.
|
||||
- `approvers`: ідентифікатори користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено підтверджувати запити exec.
|
||||
- `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Пропустіть, щоб пересилати підтвердження для всіх агентів.
|
||||
- `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
|
||||
- `target`: куди надсилати запити підтвердження. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`.
|
||||
- Перевизначення для кожного облікового запису: `channels.matrix.accounts.<id>.execApprovals`.
|
||||
- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сеанси: `per-user` (типово) спільно використовує маршрутизований peer, тоді як `per-room` ізолює кожну DM-кімнату.
|
||||
- Проби статусу Matrix і live-пошуки в каталозі використовують ту саму політику проксі, що й runtime-трафік.
|
||||
- Повну конфігурацію Matrix, правила націлювання та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix).
|
||||
|
||||
### Microsoft Teams
|
||||
|
||||
Microsoft Teams підтримується Plugin і налаштовується в `channels.msteams`.
|
||||
Microsoft Teams працює на основі Plugin і налаштовується в `channels.msteams`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -713,11 +713,11 @@ Microsoft Teams підтримується Plugin і налаштовуєтьс
|
||||
```
|
||||
|
||||
- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`.
|
||||
- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams).
|
||||
- Повну конфігурацію Teams (облікові дані, Webhook, політику DM/груп, перевизначення для кожної команди/каналу) задокументовано в [Microsoft Teams](/uk/channels/msteams).
|
||||
|
||||
### IRC
|
||||
|
||||
IRC підтримується Plugin і налаштовується в `channels.irc`.
|
||||
IRC працює на основі Plugin і налаштовується в `channels.irc`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -744,7 +744,7 @@ IRC підтримується Plugin і налаштовується в `channe
|
||||
|
||||
### Кілька облікових записів (усі канали)
|
||||
|
||||
Запустіть кілька облікових записів на канал (кожен зі своїм `accountId`):
|
||||
Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -766,29 +766,29 @@ IRC підтримується Plugin і налаштовується в `channe
|
||||
```
|
||||
|
||||
- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація).
|
||||
- Токени env застосовуються лише до **типового** облікового запису.
|
||||
- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису.
|
||||
- Env-токени застосовуються лише до **типового** облікового запису.
|
||||
- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для конкретного облікового запису.
|
||||
- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента.
|
||||
- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або onboarding каналу), усе ще маючи конфігурацію каналу верхнього рівня з одним обліковим записом, OpenClaw спочатку переносить значення одного облікового запису верхнього рівня, прив’язані до облікового запису, у мапу облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels.<channel>.accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль.
|
||||
- Наявні прив’язки лише до каналу (без `accountId`) і надалі збігаються з типовим обліковим записом; прив’язки з областю дії облікового запису залишаються необов’язковими.
|
||||
- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення одного облікового запису верхнього рівня, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль.
|
||||
- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись на конфігурації каналу верхнього рівня з одним обліковим записом, OpenClaw спочатку переносить значення верхнього рівня з областю облікового запису для одного облікового запису в карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переносять їх у `channels.<channel>.accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль.
|
||||
- Наявні прив’язки лише до каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з областю облікового запису залишаються необов’язковими.
|
||||
- `openclaw doctor --fix` також виправляє змішані форми, переносячи значення верхнього рівня з областю облікового запису для одного облікового запису в підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль.
|
||||
|
||||
### Інші Plugin-канали
|
||||
### Інші канали Plugin
|
||||
|
||||
Багато Plugin-каналів налаштовуються як `channels.<id>` і задокументовані на своїх спеціальних сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
|
||||
Див. повний індекс каналів: [Канали](/uk/channels).
|
||||
Багато каналів Plugin налаштовуються як `channels.<id>` і задокументовані на своїх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
|
||||
Дивіться повний індекс каналів: [Канали](/uk/channels).
|
||||
|
||||
### Mention gating для групового чату
|
||||
### Mention gating у груповому чаті
|
||||
|
||||
Групові повідомлення типово **вимагають mention** (metadata mention або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
|
||||
Групові повідомлення типово **вимагають mention** (metadata mention або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage.
|
||||
|
||||
Видимі відповіді керуються окремо. Групові/канальні кімнати типово мають `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw усе ще обробляє turn, але звичайні фінальні відповіді залишаються приватними, а видимий вивід у кімнаті потребує `message(action=send)`. Установлюйте `"automatic"` лише тоді, коли потрібна застаріла поведінка, за якої звичайні відповіді публікуються назад у кімнату. Щоб застосувати таку саму поведінку видимих відповідей лише через інструмент до прямих чатів також, задайте `messages.visibleReplies: "message_tool"`; Codex harness також використовує цю поведінку лише через інструмент як свій типовий варіант для прямих чатів, коли значення не задано.
|
||||
Видимі відповіді керуються окремо. Для групових/канальних кімнат типово встановлено `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw усе ще обробляє turn, але звичайні фінальні відповіді залишаються приватними, а видимий вивід у кімнату потребує `message(action=send)`. Задавайте `"automatic"` лише тоді, коли потрібна застаріла поведінка, за якої звичайні відповіді публікуються назад у кімнату. Щоб застосувати таку саму поведінку видимих відповідей лише через інструмент і до прямих чатів, задайте `messages.visibleReplies: "message_tool"`; Codex harness також використовує цю поведінку лише через інструмент як своє незадане типове значення для прямого чату.
|
||||
|
||||
Якщо інструмент повідомлень недоступний за активною політикою інструментів, OpenClaw повертається до автоматичних видимих відповідей замість мовчазного пригнічення відповіді. `openclaw doctor` попереджає про цю невідповідність.
|
||||
Якщо інструмент повідомлень недоступний у межах активної політики інструментів, OpenClaw повертається до автоматичних видимих відповідей замість того, щоб мовчки придушувати відповідь. `openclaw doctor` попереджає про цю невідповідність.
|
||||
|
||||
Gateway гаряче перезавантажує конфігурацію `messages` після збереження файлу. Перезапускайте лише тоді, коли відстеження файлів або перезавантаження конфігурації вимкнено в розгортанні.
|
||||
Gateway гаряче перезавантажує конфігурацію `messages` після збереження файлу. Перезапускайте лише тоді, коли спостереження за файлами або перезавантаження конфігурації вимкнено в розгортанні.
|
||||
|
||||
**Типи mention:**
|
||||
**Типи mentions:**
|
||||
|
||||
- **Metadata mentions**: нативні для платформи @-mentions. Ігноруються в режимі self-chat WhatsApp.
|
||||
- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються.
|
||||
@ -809,9 +809,9 @@ Gateway гаряче перезавантажує конфігурацію `mess
|
||||
}
|
||||
```
|
||||
|
||||
`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels.<channel>.historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути.
|
||||
`messages.groupChat.historyLimit` встановлює глобальне значення за замовчуванням. Канали можуть перевизначити його через `channels.<channel>.historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути.
|
||||
|
||||
`messages.visibleReplies` — це глобальне значення за замовчуванням для вихідного ходу; `messages.groupChat.visibleReplies` перевизначає його для вихідних ходів групи/каналу. Коли `messages.visibleReplies` не задано, harness може надати власне значення за замовчуванням для прямих/вихідних чатів; Codex harness за замовчуванням використовує `message_tool`. Списки дозволених каналів і фільтрація за згадками все одно визначають, чи обробляється хід.
|
||||
`messages.visibleReplies` — це глобальне значення за замовчуванням для ходу джерела; `messages.groupChat.visibleReplies` перевизначає його для ходів джерела групи/каналу. Коли `messages.visibleReplies` не задано, обв’язка може надати власне значення за замовчуванням для прямих чатів/джерела; обв’язка Codex за замовчуванням використовує `message_tool`. Списки дозволених каналів і шлюзування згадок усе одно визначають, чи обробляється хід.
|
||||
|
||||
#### Обмеження історії DM
|
||||
|
||||
@ -828,13 +828,13 @@ Gateway гаряче перезавантажує конфігурацію `mess
|
||||
}
|
||||
```
|
||||
|
||||
Визначення: перевизначення для окремого DM → значення провайдера за замовчуванням → без обмеження (зберігається все).
|
||||
Вирішення: перевизначення для окремого DM → значення за замовчуванням провайдера → без обмеження (зберігається все).
|
||||
|
||||
Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
|
||||
|
||||
#### Режим чату із собою
|
||||
|
||||
Додайте власний номер у `allowFrom`, щоб увімкнути режим чату із собою (ігнорує нативні @-згадки, відповідає лише на текстові шаблони):
|
||||
Додайте власний номер до `allowFrom`, щоб увімкнути режим чату із собою (ігнорує нативні @-згадки, відповідає лише на текстові шаблони):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -884,32 +884,32 @@ Gateway гаряче перезавантажує конфігурацію `mess
|
||||
|
||||
<Accordion title="Відомості про команди">
|
||||
|
||||
- Цей блок налаштовує поверхні команд. Поточний вбудований і bundled каталог команд див. у [Команди зі скісною рискою](/uk/tools/slash-commands).
|
||||
- Ця сторінка є **довідником ключів конфігурації**, а не повним каталогом команд. Команди, що належать каналам/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, документуються на сторінках відповідних каналів/Plugin, а також у [Команди зі скісною рискою](/uk/tools/slash-commands).
|
||||
- Цей блок налаштовує поверхні команд. Поточний вбудований і комплектний каталог команд див. у [Slash Commands](/uk/tools/slash-commands).
|
||||
- Ця сторінка є **довідником ключів конфігурації**, а не повним каталогом команд. Команди, що належать каналам/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, сполучення пристрою `/pair`, пам’ять `/dreaming`, керування телефоном `/phone` і Talk `/voice`, документуються на сторінках відповідних каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands).
|
||||
- Текстові команди мають бути **окремими** повідомленнями з початковим `/`.
|
||||
- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим.
|
||||
- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим.
|
||||
- Перевизначення для каналу: `channels.discord.commands.native` (логічне значення або `"auto"`). Для Discord `false` пропускає реєстрацію нативних команд і очищення під час запуску.
|
||||
- Перевизначайте реєстрацію нативних Skills для каналу через `channels.<provider>.commands.nativeSkills`.
|
||||
- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram.
|
||||
- `bash: true` вмикає `! <cmd>` для shell хоста. Потребує `tools.elevated.enabled` і відправника в `tools.elevated.allowFrom.<channel>`.
|
||||
- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; `/config show` лише для читання залишається доступним звичайним клієнтам операторів з областю запису.
|
||||
- `mcp: true` вмикає `/mcp` для конфігурації MCP-серверів, керованих OpenClaw, у `mcp.servers`.
|
||||
- `plugins: true` вмикає `/plugins` для виявлення, встановлення та керування ввімкненням/вимкненням Plugin.
|
||||
- `channels.<provider>.configWrites` обмежує зміни конфігурації для каналу (за замовчуванням: true).
|
||||
- Для каналів із кількома обліковими записами `channels.<provider>.accounts.<id>.configWrites` також обмежує записи, націлені на цей обліковий запис (наприклад, `/allowlist --config --account <id>` або `/config set channels.<provider>.accounts.<id>...`).
|
||||
- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. За замовчуванням: `true`.
|
||||
- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`.
|
||||
- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням.
|
||||
- `allowFrom` задається для кожного провайдера. Коли його встановлено, це **єдине** джерело авторизації (списки дозволених каналів/сполучення та `useAccessGroups` ігноруються).
|
||||
- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено.
|
||||
- Перевизначення для каналу: `channels.discord.commands.native` (булеве значення або `"auto"`). Для Discord значення `false` пропускає реєстрацію нативних команд і очищення під час запуску.
|
||||
- Перевизначте реєстрацію нативних Skills для каналу через `channels.<provider>.commands.nativeSkills`.
|
||||
- `channels.telegram.customCommands` додає додаткові пункти меню Telegram-бота.
|
||||
- `bash: true` вмикає `! <cmd>` для оболонки хоста. Потребує `tools.elevated.enabled` і відправника в `tools.elevated.allowFrom.<channel>`.
|
||||
- `config: true` вмикає `/config` (читає/записує `openclaw.json`). Для клієнтів `chat.send` Gateway постійні записи `/config set|unset` також потребують `operator.admin`; доступна лише для читання команда `/config show` залишається доступною для звичайних клієнтів оператора з областю запису.
|
||||
- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, керованого OpenClaw, у `mcp.servers`.
|
||||
- `plugins: true` вмикає `/plugins` для виявлення Plugin, встановлення та керування ввімкненням/вимкненням.
|
||||
- `channels.<provider>.configWrites` обмежує мутації конфігурації для каналу (за замовчуванням: true).
|
||||
- Для каналів із кількома обліковими записами `channels.<provider>.accounts.<id>.configWrites` також обмежує записи, спрямовані на цей обліковий запис (наприклад, `/allowlist --config --account <id>` або `/config set channels.<provider>.accounts.<id>...`).
|
||||
- `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. За замовчуванням: `true`.
|
||||
- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`.
|
||||
- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному промпті. Задайте `ownerDisplaySecret`, щоб керувати хешуванням.
|
||||
- `allowFrom` задається для кожного провайдера. Коли встановлено, це **єдине** джерело авторизації (списки дозволених каналів/сполучення та `useAccessGroups` ігноруються).
|
||||
- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не задано.
|
||||
- Мапа документації команд:
|
||||
- вбудований і bundled каталог: [Команди зі скісною рискою](/uk/tools/slash-commands)
|
||||
- вбудований і комплектний каталог: [Slash Commands](/uk/tools/slash-commands)
|
||||
- поверхні команд для окремих каналів: [Канали](/uk/channels)
|
||||
- команди QQ Bot: [QQ Bot](/uk/channels/qqbot)
|
||||
- команди сполучення: [Сполучення](/uk/channels/pairing)
|
||||
- команда картки LINE: [LINE](/uk/channels/line)
|
||||
- Dreaming пам’яті: [Dreaming](/uk/concepts/dreaming)
|
||||
- memory dreaming: [Dreaming](/uk/concepts/dreaming)
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user