chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
e17e50ef2d
commit
b4e23dc7c3
File diff suppressed because it is too large
Load Diff
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота з функціями Telegram або вебхуками
|
||||
summary: Стан підтримки Telegram-бота, можливості та налаштування
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Стан підтримки, можливості та конфігурація бота Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T06:09:35Z"
|
||||
generated_at: "2026-05-02T09:29:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: af04e95d6011ab568e07c309bc7c154d9242a53e24b7f52a2381dbf30ed842a0
|
||||
source_hash: dde2a15c6529365e6174f8e0640c1955b63fdfafa952b675159db93c5d43041c
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово до продакшену для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим webhook необов’язковий.
|
||||
Готово до продакшену для DM ботів і груп через grammY. Довге опитування є стандартним режимом; режим Webhook необовʼязковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика DM для Telegram — сполучення.
|
||||
<Card title="Спарювання" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика DM для Telegram — спарювання.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Кросканальна діагностика та інструкції з відновлення.
|
||||
Міжканальна діагностика й інструкції з відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
@ -30,9 +30,9 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
Відкрийте Telegram і поспілкуйтеся з **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -51,8 +51,8 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний env-варіант: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway.
|
||||
Резервне значення env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -64,31 +64,31 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди сполучення діють 1 годину.
|
||||
Коди спарювання спливають через 1 годину.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте бота до групи">
|
||||
Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env-значенням, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним значенням env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
## Налаштування на стороні Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
<Accordion title="Режим приватності та видимість груп">
|
||||
Для ботів Telegram стандартно ввімкнено **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з цього:
|
||||
Якщо бот має бачити всі групові повідомлення, зробіть одне з такого:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -107,38 +107,38 @@ openclaw pairing approve telegram <CODE>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Контроль доступу й активація
|
||||
## Контроль доступу та активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `pairing` (стандартно)
|
||||
- `allowlist` (потребує принаймні одного ID відправника в `allowFrom`)
|
||||
- `open` (потребує, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає імʼя користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня вважається межею безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття все ще не містить явного wildcard.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою конфігурації.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний список allowlist облікового запису після обʼєднання все ще не містить явного wildcard.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (найкраща спроба; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
Якщо ви оновилися й ваша конфігурація містить записи 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`, щоб політика доступу була надійно зафіксована в конфігурації (замість залежності від попередніх схвалень спарювання).
|
||||
|
||||
Поширена плутанина: схвалення DM-сполучення не означає «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все одно походить з явних allowlist у конфігурації.
|
||||
Якщо ви хочете «я авторизований один раз, і працюють і DM, і групові команди», додайте свій числовий 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. Надішліть DM своєму боту.
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
@ -158,25 +158,25 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає конфігурації `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки group-ID
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- з `groupPolicy: "allowlist"` (стандартно): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `allowlist` (стандартно)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групі. Якщо не задано, Telegram повертається до `allowFrom`.
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища DM-сполучень.
|
||||
Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень.
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Відʼємні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища спарювання DM.
|
||||
Спарювання лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища спарювання.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime стандартно закривається без доступу з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи:
|
||||
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,18 +211,18 @@ 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`, коли хочете обмежити, хто саме в дозволеній групі може запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
|
||||
- Додавайте відʼємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, до `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, до `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Поведінка згадок">
|
||||
Групові відповіді за замовчуванням потребують згадки.
|
||||
Групові відповіді стандартно потребують згадки.
|
||||
|
||||
Згадка може надходити з:
|
||||
|
||||
@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд на рівні сесії:
|
||||
Перемикачі команд рівня сеансу:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для сталості використовуйте конфігурацію.
|
||||
Вони оновлюють лише стан сеансу. Для збереження використовуйте конфігурацію.
|
||||
|
||||
Приклад сталої конфігурації:
|
||||
|
||||
@ -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>
|
||||
@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді й заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми лишалися ізольованими.
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає thread ID для відповідей.
|
||||
- Long polling використовує grammY runner із послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений усередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller.
|
||||
- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски polling-stall під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб тримати теми ізольованими.
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але стандартно лишає DM у плоскому сеансі. Налаштуйте `channels.telegram.direct.<chatId>.threadReplies: "inbound"` або `requireTopic: true`, коли навмисно хочете ізоляцію сеансів за темами DM.
|
||||
- Довге опитування використовує 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` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
<Accordion title="Live stream preview (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
- прямі чати: preview-повідомлення + `editMessageText`
|
||||
- групи/теми: preview-повідомлення + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` відображається на `partial` у Telegram (сумісність із кросканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний preview streaming)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (стандартно: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане preview-повідомлення (стандартно: `true`, коли preview streaming активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і новіших версій. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Preview-оновлення прогресу інструментів — це короткі рядки "Working...", які показуються під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram лишає їх увімкненими стандартно, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніше. Щоб зберегти редагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,43 +306,43 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальний службовий текст інструментів/прогресу приглушується замість надсилання як окремі повідомлення «Працюємо...». Запити на схвалення, медіа payloads і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду в Telegram вимикаються, а звичайні повідомлення інструментів/прогресу пригнічуються замість надсилання окремими повідомленнями "Working...". Запити на схвалення, медіа-вміст і помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховуючи рядки стану прогресу інструментів.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад, медіа payloads) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Потокове передавання попереднього перегляду відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерування
|
||||
- `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерації
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
<Accordion title="Форматування й резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Markdown-подібний текст відтворюється як безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити збої розбору Telegram.
|
||||
- Текст у стилі Markdown відтворюється як HTML, безпечний для Telegram.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
<Accordion title="Нативні команди й власні команди">
|
||||
Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
Додайте користувацькі записи меню команд:
|
||||
Додайте власні записи меню команд:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -359,47 +359,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- імена нормалізуються (видаляється початковий `/`, переводиться в нижній регістр)
|
||||
- імена нормалізуються (прибирається початковий `/`, нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й записуються в журнал
|
||||
- власні команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й журналюються
|
||||
|
||||
Примітки:
|
||||
Нотатки:
|
||||
|
||||
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- власні команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill усе одно можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо налаштовані.
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Власні команди або команди plugin усе ще можуть реєструватися, якщо це налаштовано.
|
||||
|
||||
Поширені збої налаштування:
|
||||
Поширені помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повний endpoint `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `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` було встановлено на повну кінцеву точку `/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` заблоковано.
|
||||
- `setMyCommands failed` з помилками мережі/завантаження зазвичай означає, що вихідні DNS/HTTPS-з'єднання до `api.telegram.org` заблоковані.
|
||||
|
||||
### Команди сполучення пристрою (plugin `device-pair`)
|
||||
### Команди сполучення пристроїв (`device-pair` plugin)
|
||||
|
||||
Коли встановлено plugin `device-pair`:
|
||||
Коли встановлено `device-pair` plugin:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` перелічує запити в очікуванні (включно з роллю/областями)
|
||||
2. вставте код у застосунку iOS
|
||||
3. `/pair pending` перелічує запити в очікуванні (зокрема роль/області)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один запит в очікуванні
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування переносить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий операторський токен залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише операторські запити; неоператорські ролі все одно потребують областей під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно запустіть `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані кнопки">
|
||||
Налаштуйте область вбудованої клавіатури:
|
||||
Налаштуйте область дії вбудованої клавіатури:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Натискання callback передаються агенту як текст:
|
||||
Кліки callback передаються агенту як текст:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
@ -467,15 +467,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов'язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов'язкові `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Елементи керування обмеженнями:
|
||||
Керування обмеженнями:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -483,16 +483,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
|
||||
Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціальне повторне розв'язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги потоків відповідей">
|
||||
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги гілок відповідей">
|
||||
Telegram підтримує явні теги гілок відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, яке запустило обробку
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
@ -501,29 +501,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Коли потоки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
Коли гілки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються.
|
||||
Примітка: `off` вимикає неявні гілки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка потоків">
|
||||
<Accordion title="Теми форуму й поведінка гілок">
|
||||
Форумні супергрупи:
|
||||
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору спрямовуються в потік теми
|
||||
- ключі сесій теми додають `:topic:<threadId>`
|
||||
- відповіді й індикація набору спрямовуються в гілку теми
|
||||
- шлях конфігурації теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
Особливий випадок загальної теми (`threadId=1`):
|
||||
|
||||
- надсилання повідомлень пропускають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору все ще включають `message_thread_id`
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все одно включають `message_thread_id`
|
||||
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише до теми й не успадковується з типових значень групи.
|
||||
Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` стосується лише теми й не успадковується з типових налаштувань групи.
|
||||
|
||||
**Маршрутизація агентів для кожної теми**: кожна тема може маршрутизуватися до іншого агента через установлення `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизувати до іншого агента, якщо встановити `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам'ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -543,26 +543,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та topic-кваліфікованим id на кшталт `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
**Стійке прив'язування тем ACP**: Теми форуму можуть закріплювати сесії ACP harness через типізовані прив'язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
**Створення ACP, прив’язане до потоку, з чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`).
|
||||
**Запуск ACP, прив'язаний до гілки, з чату**: `/acp spawn <agent> --thread here|auto` прив'язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`).
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням потоку.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM і метадані відповіді; вони використовують ключі сесій з урахуванням гілок лише тоді, коли DM налаштовано з `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідною конфігурацією теми.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Аудіо, відео та стікери">
|
||||
<Accordion title="Аудіо, відео й наліпки">
|
||||
### Аудіоповідомлення
|
||||
|
||||
Telegram розрізняє голосові нотатки та аудіофайли.
|
||||
Telegram розрізняє голосові нотатки й аудіофайли.
|
||||
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку
|
||||
- вхідні транскрипти голосових нотаток оформлюються як машинно згенерований,
|
||||
ненадійний текст у контексті агента; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тому голосові повідомлення з gating за згадкою продовжують працювати.
|
||||
ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -578,7 +578,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Відеоповідомлення
|
||||
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
Telegram розрізняє відеофайли й відеонотатки.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -594,15 +594,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо.
|
||||
|
||||
### Стікери
|
||||
### Наліпки
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
Обробка вхідних наліпок:
|
||||
|
||||
- статичний WEBP: завантажується й обробляється (placeholder `<media:sticker>`)
|
||||
- статичний WEBP: завантажується й обробляється (заповнювач `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
Поля контексту стікера:
|
||||
Поля контексту наліпки:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -610,13 +610,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `Sticker.fileUniqueId`
|
||||
- `Sticker.cachedDescription`
|
||||
|
||||
Файл кешу стікерів:
|
||||
Файл кешу наліпок:
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision.
|
||||
Наліпки описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору.
|
||||
|
||||
Увімкніть дії зі стікерами:
|
||||
Увімкніть дії з наліпками:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -630,7 +630,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Дія надсилання стікера:
|
||||
Дія надсилання наліпки:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -655,7 +655,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payloads повідомлень).
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлення).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
@ -663,44 +663,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Конфігурація:
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`)
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`)
|
||||
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID гілок у оновленнях реакцій.
|
||||
- групи не-форуми маршрутизуються до сесії групового чату
|
||||
- форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори потоків в оновленнях реакцій.
|
||||
- групи без форумів маршрутизуються до сесії групового чату
|
||||
- групи з форумами маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Реакції підтвердження">
|
||||
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
<Accordion title="Ack-реакції">
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Нотатки:
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує unicode emoji (наприклад "👀").
|
||||
- Використайте `""`, щоб вимкнути реакцію для каналу або акаунта.
|
||||
- Telegram очікує unicode-емодзі (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Записи конфігурації з подій і команд Telegram">
|
||||
Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`).
|
||||
Записи конфігурації каналу ввімкнені типово (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команд)
|
||||
|
||||
Вимкнення:
|
||||
@ -718,37 +718,37 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON body перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі lane-и бота для кожного чату/кожної теми, що й у long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
Режим Webhook перевіряє захисти запитів, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw асинхронно обробляє оновлення через ті самі bot lanes для кожного чату/кожної теми, що використовуються long polling, тому повільні ходи агента не затримують delivery ACK Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби та цілі CLI">
|
||||
- `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000.
|
||||
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає timeout API-клієнта Telegram (якщо не задано, застосовується стандартне значення grammY). Клієнти бота з long-polling обмежують налаштовані значення нижче 45-секундного guard запиту `getUpdates`, щоб idle polls не переривалися до завершення 30-секундного вікна poll.
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
|
||||
- додатковий контекст reply/quote/forward наразі передається як отриманий.
|
||||
- Allowlist-и Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів long-polling обмежують налаштовані значення нижче за 45-секундний захист запиту `getUpdates`, щоб idle polls не переривалися до завершення 30-секундного вікна опитування.
|
||||
- `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через polling-stall.
|
||||
- Історія групового контексту використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
|
||||
- Додатковий контекст відповіді/цитати/пересилання наразі передається так, як отриманий.
|
||||
- Allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Елементи керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної відповіді на вхідні повідомлення також використовує обмежений safe-send retry для помилок Telegram до підключення, але не повторює неоднозначні мережеві envelopes після надсилання, які могли б дублювати видимі повідомлення.
|
||||
- Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. Доставка фінальної вхідної відповіді також використовує обмежену повторну спробу безпечного надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві envelope після надсилання, які могли б дублювати видимі повідомлення.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або username:
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Poll-и Telegram використовують `openclaw message poll` і підтримують форумні теми:
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують теми форумів:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -758,57 +758,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Прапорці poll лише для Telegram:
|
||||
Прапорці опитувань лише для Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для форумних тем (або використайте ціль `:topic:`)
|
||||
- `--thread-id` для тем форумів (або використовуйте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для inline keyboards, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media
|
||||
- `--force-document`, щоб надсилати вихідні зображення й GIF як документи замість стиснених фото або завантажень animated-media
|
||||
|
||||
Обмеження дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з poll-ами
|
||||
- `channels.telegram.actions.poll=false` вимикає створення poll-ів Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec approvals у Telegram">
|
||||
Telegram підтримує exec approvals у DM approver-ів і може необов’язково публікувати prompts у початковому чаті або темі. Approver-и мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM підтверджувачів і може необов’язково публікувати prompts у початковому чаті або темі. Підтверджувачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного approver-а)
|
||||
- `channels.telegram.execApprovals.approvers` (fallback до числових ID власників з `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного підтверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver-ом. Перше схвалене DM pairing bootstrap-ить `commands.ownerAllowFrom`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось підтверджувачем exec. Перше затверджене спарювання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником і далі працює без дублювання ID у `execApprovals.approvers`.
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для prompt-а схвалення та наступного повідомлення. Exec approvals за замовчуванням спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє в тему форуму, OpenClaw зберігає тему для prompt підтвердження та подальшого повідомлення. Підтвердження exec типово спливають через 30 хвилин.
|
||||
|
||||
Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалення з префіксом `plugin:` визначаються через approvals Plugin; інші спочатку визначаються через exec approvals.
|
||||
Кнопки inline-підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` визначаються через підтвердження plugin; інші спочатку визначаються через підтвердження exec.
|
||||
|
||||
Див. [Exec approvals](/uk/tools/exec-approvals).
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Керування відповідями про помилки
|
||||
## Елементи керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або provider-а, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації:
|
||||
Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації:
|
||||
|
||||
| Ключ | Значення | За замовчуванням | Опис |
|
||||
| ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час outages. |
|
||||
| Ключ | Значення | Типово | Опис |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилок під час перебоїв. |
|
||||
|
||||
Підтримуються перевизначення для кожного акаунта, групи та теми (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
Підтримуються перевизначення для кожного облікового запису, кожної групи та кожної теми (таке саме успадкування, як для інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -831,53 +831,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на групові повідомлення без згадки">
|
||||
|
||||
- Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість.
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на membership.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот узагалі не бачить групові повідомлення">
|
||||
<Accordion title="Бот взагалі не бачить групові повідомлення">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана (або включати `"*"`)
|
||||
- перевірте membership бота в групі
|
||||
- перегляньте логи: `openclaw logs --follow` для причин пропуску
|
||||
- коли `channels.telegram.groups` існує, група має бути в списку (або включати `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або не працюють зовсім">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (pairing і/або числовий `allowFrom`)
|
||||
- авторизуйте ідентичність свого відправника (спарювання та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість команд Plugin/Skills/custom або вимкніть нативні меню
|
||||
- стартові виклики `deleteMyCommands` / `setMyCommands` обмежені та повторюються один раз через транспортний fallback Telegram у разі timeout запиту. Постійні помилки network/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість plugin/skill/користувацьких команд або вимкніть нативні меню
|
||||
- startup-виклики `deleteMyCommands` / `setMyCommands` обмежені й повторюються один раз через транспортний fallback Telegram у разі timeout запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований токен">
|
||||
<Accordion title="Startup повідомляє про неавторизований токен">
|
||||
|
||||
- `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для акаунта за замовчуванням.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є помилкою auth; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API.
|
||||
- Якщо `deleteWebhook` завершується з transient network error під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній webhook URL, polling продовжується, бо очищення вже задоволено.
|
||||
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте заново токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час startup — це також збій автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій поганого токена до пізніших API-викликів.
|
||||
- Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час polling startup, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо cleanup уже виконано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
|
||||
- Node 22+ + власний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний IPv6 egress може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
|
||||
- Якщо сокети Telegram повторно створюються з коротким фіксованим інтервалом, перевірте, чи не замалий `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче запобіжника запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
|
||||
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис із polling не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис із webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність polling-транспорту застаріла.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли тривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через polling-stall. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- Telegram також враховує proxy env процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й стандартних proxy env немає, Telegram також використовує цю URL-адресу для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ + користувацький fetch/proxy може спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці спроби як відновлювані мережеві помилки.
|
||||
- Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не задано низьке значення `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче захисного ліміту запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
|
||||
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис з опитуванням не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність транспорту опитування застаріла.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми проксі, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`.
|
||||
- Telegram також враховує змінні середовища проксі процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
|
||||
- Якщо керований проксі OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й немає стандартної змінної середовища проксі, Telegram також використовує цей URL для транспорту Bot API.
|
||||
- На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -885,7 +885,7 @@ 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`.
|
||||
- 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
|
||||
@ -895,10 +895,10 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді з діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете
|
||||
прозорий проксі переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантаження медіа, ви можете
|
||||
увімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
@ -908,25 +908,25 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Та сама опція доступна для кожного облікового запису за адресою
|
||||
- Такий самий явний дозвіл доступний для кожного облікового запису в
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
|
||||
бенчмарків RFC 2544 за замовчуванням.
|
||||
- Якщо ваш проксі розв’язує медіахости Telegram у `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон RFC 2544
|
||||
для бенчмаркінгу за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти Telegram
|
||||
media від SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy
|
||||
середовищ, таких як Clash, Mihomo або Surge fake-IP routing, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном бенчмарків
|
||||
RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет.
|
||||
media SSRF. Використовуйте це лише для довірених проксі-середовищ, контрольованих оператором,
|
||||
як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном RFC 2544 для
|
||||
бенчмаркінгу. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення середовища (тимчасові):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Перевірте відповіді DNS:
|
||||
- Перевірте DNS-відповіді:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -936,23 +936,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">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`)
|
||||
- схвалення exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
|
||||
- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
@ -962,14 +962,14 @@ 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.
|
||||
Зв’яжіть користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/uk/channels/groups">
|
||||
Поведінка списку дозволених груп і тем.
|
||||
@ -984,6 +984,6 @@ dig +short api.telegram.org AAAA
|
||||
Зіставляйте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами.
|
||||
Міжканальна діагностика.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви налагоджуєте встановлення пакетів плагінів
|
||||
- Ви змінюєте поведінку запуску Plugin, doctor або встановлення через менеджер пакетів
|
||||
- Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести Plugin, що постачаються в комплекті
|
||||
- Ви налагоджуєте встановлення пакетів Plugin
|
||||
- Ви змінюєте поведінку запуску Plugin, діагностики або встановлення через менеджер пакетів
|
||||
- Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести вбудованих Plugin
|
||||
sidebarTitle: Dependencies
|
||||
summary: Як OpenClaw встановлює Plugin-пакети та розв’язує залежності Plugin
|
||||
title: Розв’язання залежностей Plugin
|
||||
summary: Як OpenClaw встановлює пакети Plugin і розв’язує залежності Plugin
|
||||
title: Вирішення залежностей Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T02:02:07Z"
|
||||
generated_at: "2026-05-02T09:29:42Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 43d8008c837d519fd7c886f9615ad53941da340d753b559dfb0a32877716bc1f
|
||||
source_hash: c9476529ad1d44ed1b17caca628c58acfbb1d8c73393f58fa7d3d76944a71aea
|
||||
source_path: plugins/dependency-resolution.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -25,11 +25,11 @@ OpenClaw виконує роботу із залежностями Plugin під
|
||||
|
||||
Пакети Plugin відповідають за власний граф залежностей:
|
||||
|
||||
- залежності часу виконання розміщуються в `dependencies` або
|
||||
- залежності часу виконання містяться в `dependencies` або
|
||||
`optionalDependencies` пакета Plugin
|
||||
- імпорти SDK/ядра є peer-імпортами або наданими імпортами OpenClaw
|
||||
- локальні Plugin для розробки постачаються зі своїми вже встановленими залежностями
|
||||
- npm і git Plugin установлюються в корені пакетів, що належать OpenClaw
|
||||
- імпорти SDK/core є peer-імпортами або імпортами, наданими OpenClaw
|
||||
- локальні Plugin для розробки мають власні вже встановлені залежності
|
||||
- npm- і git-Plugin установлюються в корені пакетів, якими керує OpenClaw
|
||||
|
||||
OpenClaw відповідає лише за життєвий цикл Plugin:
|
||||
|
||||
@ -37,54 +37,54 @@ OpenClaw відповідає лише за життєвий цикл Plugin:
|
||||
- установити або оновити пакет, коли це явно запитано
|
||||
- записати метадані встановлення
|
||||
- завантажити точку входу Plugin
|
||||
- завершити роботу з дієвою помилкою, коли залежності відсутні
|
||||
- завершити з дієвою помилкою, коли залежностей бракує
|
||||
|
||||
## Корені встановлення
|
||||
|
||||
OpenClaw використовує стабільні корені для кожного джерела:
|
||||
|
||||
- пакети npm установлюються в `~/.openclaw/npm`
|
||||
- пакети git клонуються в `~/.openclaw/git`
|
||||
- локальні/шляхові/архівні встановлення копіюються або використовуються за посиланням без ремонту залежностей
|
||||
- npm-пакети встановлюються в `~/.openclaw/npm`
|
||||
- git-пакети клонуються в `~/.openclaw/git`
|
||||
- локальні/path/archive-встановлення копіюються або використовуються за посиланням без ремонту залежностей
|
||||
|
||||
Встановлення npm виконуються в корені npm за допомогою:
|
||||
npm-встановлення виконуються в корені npm за допомогою:
|
||||
|
||||
```bash
|
||||
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
```
|
||||
|
||||
npm може підняти транзитивні залежності до `~/.openclaw/npm/node_modules` поруч із
|
||||
пакетом Plugin. OpenClaw сканує керований корінь npm перед тим, як довіряти
|
||||
npm може піднімати транзитивні залежності в `~/.openclaw/npm/node_modules` поруч
|
||||
із пакетом Plugin. OpenClaw сканує керований корінь npm, перш ніж довіряти
|
||||
встановленню, і використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті
|
||||
залежності часу виконання залишаються всередині керованої межі очищення.
|
||||
залежності часу виконання залишаються в межах керованого очищення.
|
||||
|
||||
Встановлення git клонують або оновлюють репозиторій, а потім виконують:
|
||||
git-встановлення клонують або оновлюють репозиторій, а потім виконують:
|
||||
|
||||
```bash
|
||||
npm install --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
```
|
||||
|
||||
Після цього встановлений Plugin завантажується з каталогу цього пакета, тому розв’язання
|
||||
локальних для пакета та батьківських `node_modules` працює так само, як для звичайного
|
||||
пакета Node.
|
||||
package-local і батьківських `node_modules` працює так само, як для звичайного
|
||||
Node-пакета.
|
||||
|
||||
## Локальні Plugin
|
||||
|
||||
Локальні Plugin розглядаються як каталоги, керовані розробником. OpenClaw не
|
||||
виконує для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний
|
||||
Локальні Plugin розглядаються як каталоги, контрольовані розробником. OpenClaw не
|
||||
запускає для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний
|
||||
Plugin має залежності, установіть їх у цьому Plugin перед його завантаженням.
|
||||
|
||||
Сторонні локальні Plugin TypeScript можуть використовувати аварійний шлях Jiti. Запаковані
|
||||
JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативні
|
||||
Сторонні локальні TypeScript-Plugin можуть використовувати аварійний шлях Jiti. Пакетовані
|
||||
JavaScript-Plugin і вбудовані внутрішні Plugin завантажуються через нативний
|
||||
import/require замість Jiti.
|
||||
|
||||
## Запуск і перезавантаження
|
||||
|
||||
Запуск Gateway і перезавантаження конфігурації ніколи не встановлюють залежності Plugin. Вони читають
|
||||
записи встановлення Plugin, обчислюють точку входу та завантажують її.
|
||||
записи встановлення Plugin, обчислюють точку входу й завантажують її.
|
||||
|
||||
Якщо залежність відсутня під час виконання, Plugin не завантажується, а помилка
|
||||
має вказати оператору явне виправлення:
|
||||
Якщо залежності бракує під час виконання, Plugin не завантажується, а помилка
|
||||
має спрямувати оператора до явного виправлення:
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id>
|
||||
@ -93,37 +93,40 @@ openclaw doctor --fix
|
||||
```
|
||||
|
||||
`doctor --fix` може очистити застарілий стан залежностей, згенерований OpenClaw, і встановити
|
||||
налаштовані завантажувані Plugin, яких немає в локальних записах встановлення.
|
||||
налаштовані завантажувані Plugin, яких бракує в локальних записах встановлення.
|
||||
Він не ремонтує залежності для вже встановленого локального Plugin.
|
||||
|
||||
## Вбудовані Plugin
|
||||
|
||||
Легкі та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw.
|
||||
Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені в
|
||||
завантажуваний пакет на ClawHub/npm.
|
||||
Легковагові та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw.
|
||||
Вони або не повинні мати важкого дерева залежностей часу виконання, або мають бути винесені
|
||||
в завантажуваний пакет на ClawHub/npm.
|
||||
|
||||
Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велику або необов’язкову
|
||||
функціональність Plugin слід пакувати як звичайний Plugin і встановлювати через
|
||||
Поточний згенерований список Plugin, які постачаються в основному пакеті, встановлюються
|
||||
зовнішньо або залишаються лише у вихідному коді, див. в [інвентарі Plugin](/uk/plugins/plugin-inventory).
|
||||
|
||||
Маніфести вбудованих Plugin не повинні запитувати стадіювання залежностей. Велика або необов’язкова
|
||||
функціональність Plugin має пакуватися як звичайний Plugin і встановлюватися через
|
||||
той самий шлях npm/git/ClawHub, що й сторонні Plugin.
|
||||
|
||||
У вихідних checkout OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після
|
||||
`pnpm install` вбудовані Plugin завантажуються з `extensions/<id>`, тож локальні для пакета
|
||||
залежності workspace доступні, а зміни підхоплюються напряму. Розробка з вихідного
|
||||
checkout підтримується лише з pnpm; звичайний `npm install` у корені репозиторію
|
||||
У checkout-ах вихідного коду OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після
|
||||
`pnpm install` вбудовані Plugin завантажуються з `extensions/<id>`, тож package-local
|
||||
залежності workspace доступні, а зміни підхоплюються напряму. Розробка в checkout-і
|
||||
вихідного коду підтримується лише з pnpm; звичайний `npm install` у корені репозиторію
|
||||
не є підтримуваним способом підготувати залежності вбудованих Plugin.
|
||||
|
||||
| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей |
|
||||
| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей |
|
||||
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
|
||||
| `npm install -g openclaw` | Побудоване дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin |
|
||||
| Git checkout плюс `pnpm install` | Пакети workspace `extensions/<id>` | pnpm workspace, включно з власними залежностями кожного пакета Plugin |
|
||||
| Git checkout plus `pnpm install` | Workspace-пакети `extensions/<id>` | pnpm-workspace, включно з власними залежностями кожного пакета Plugin |
|
||||
| `openclaw plugins install ...` | Керований корінь Plugin npm/git/ClawHub | Потік встановлення/оновлення Plugin |
|
||||
|
||||
## Очищення застарілого стану
|
||||
|
||||
Старіші версії OpenClaw генерували корені залежностей вбудованих Plugin під час запуску або
|
||||
під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги та
|
||||
символьні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`,
|
||||
маніфестами `.openclaw-runtime-deps*`, згенерованими `node_modules` Plugin, каталогами
|
||||
етапів встановлення та локальними для пакета сховищами pnpm.
|
||||
під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги й
|
||||
символьні посилання, коли використовується `--fix`, зокрема старі корені `plugin-runtime-deps`,
|
||||
маніфести `.openclaw-runtime-deps*`, згенеровані `node_modules` Plugin, каталоги
|
||||
стадії встановлення та package-local pnpm-сховища.
|
||||
|
||||
Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
164
docs/uk/plugins/plugin-inventory.md
Normal file
164
docs/uk/plugins/plugin-inventory.md
Normal file
@ -0,0 +1,164 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви вирішуєте, чи постачається Plugin у основному пакеті npm, чи встановлюється окремо
|
||||
- Ви оновлюєте метадані пакета вбудованого Plugin або автоматизацію випуску
|
||||
- Вам потрібен канонічний список внутрішніх і зовнішніх плагінів
|
||||
summary: Згенерований інвентар плагінів OpenClaw, що постачаються в ядрі, публікуються зовнішньо або зберігаються лише у вихідному коді
|
||||
title: Інвентаризація Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:29:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 49e4471cfd5e217e0ac8a55d3ed942c8b32f2606fdcfe19797144038d5eb75e2
|
||||
source_path: plugins/plugin-inventory.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Інвентар Plugin
|
||||
|
||||
Ця сторінка згенерована з `extensions/*/package.json`, `openclaw.plugin.json`,
|
||||
і виключень `files` кореневого npm-пакета. Перегенеруйте її за допомогою:
|
||||
|
||||
```bash
|
||||
pnpm plugins:inventory:gen
|
||||
```
|
||||
|
||||
## Визначення
|
||||
|
||||
- **Основний npm-пакет:** вбудований у npm-пакет `openclaw` і доступний без окремого встановлення Plugin.
|
||||
- **Офіційний зовнішній пакет:** Plugin, який підтримує OpenClaw, вилучений з основного npm-пакета та встановлюється через ClawHub і/або npm.
|
||||
- **Лише checkout вихідного коду:** локальний для репозиторію Plugin, вилучений з опублікованих npm-артефактів і не рекламується як пакет, доступний для встановлення.
|
||||
|
||||
Checkout-и вихідного коду відрізняються від встановлень npm: після `pnpm install` вбудовані
|
||||
Plugin завантажуються з `extensions/<id>`, тому локальні зміни та локальні для пакета workspace-залежності
|
||||
доступні.
|
||||
|
||||
## Основний npm-пакет
|
||||
|
||||
| Plugin | Пакет | Поверхня | Документація | Встановлення |
|
||||
| --------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------- |
|
||||
| alibaba | `@openclaw/alibaba-provider` | contracts: videoGenerationProviders | [alibaba](/uk/providers/alibaba) | включено до OpenClaw |
|
||||
| amazon-bedrock | `@openclaw/amazon-bedrock-provider` | providers: amazon-bedrock; contracts: memoryEmbeddingProviders | [amazon-bedrock](/uk/providers/bedrock) | включено до OpenClaw |
|
||||
| amazon-bedrock-mantle | `@openclaw/amazon-bedrock-mantle-provider` | providers: amazon-bedrock-mantle | [amazon-bedrock-mantle](/uk/providers/bedrock-mantle) | включено до OpenClaw |
|
||||
| anthropic | `@openclaw/anthropic-provider` | providers: anthropic; contracts: mediaUnderstandingProviders | [anthropic](/uk/providers/anthropic) | включено до OpenClaw |
|
||||
| anthropic-vertex | `@openclaw/anthropic-vertex-provider` | providers: anthropic-vertex | - | включено до OpenClaw |
|
||||
| arcee | `@openclaw/arcee-provider` | providers: arcee | [arcee](/uk/providers/arcee) | включено до OpenClaw |
|
||||
| azure-speech | `@openclaw/azure-speech` | contracts: speechProviders | [azure-speech](/uk/providers/azure-speech) | включено до OpenClaw |
|
||||
| bonjour | `@openclaw/bonjour` | plugin | - | включено до OpenClaw |
|
||||
| browser | `@openclaw/browser-plugin` | contracts: tools; skills | [browser](/uk/tools/browser) | включено до OpenClaw |
|
||||
| byteplus | `@openclaw/byteplus-provider` | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders | - | включено до OpenClaw |
|
||||
| cerebras | `@openclaw/cerebras-provider` | providers: cerebras | [cerebras](/uk/providers/cerebras) | включено до OpenClaw |
|
||||
| chutes | `@openclaw/chutes-provider` | providers: chutes | [chutes](/uk/providers/chutes) | включено до OpenClaw |
|
||||
| cloudflare-ai-gateway | `@openclaw/cloudflare-ai-gateway-provider` | providers: cloudflare-ai-gateway | [cloudflare-ai-gateway](/uk/providers/cloudflare-ai-gateway) | включено до OpenClaw |
|
||||
| comfy | `@openclaw/comfy-provider` | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders | [comfy](/uk/providers/comfy) | включено до OpenClaw |
|
||||
| copilot-proxy | `@openclaw/copilot-proxy` | providers: copilot-proxy | - | включено до OpenClaw |
|
||||
| deepgram | `@openclaw/deepgram-provider` | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders | [deepgram](/uk/providers/deepgram) | включено до OpenClaw |
|
||||
| deepinfra | `@openclaw/deepinfra-provider` | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders | [deepinfra](/uk/providers/deepinfra) | включено до OpenClaw |
|
||||
| deepseek | `@openclaw/deepseek-provider` | providers: deepseek | [deepseek](/uk/providers/deepseek) | включено до OpenClaw |
|
||||
| document-extract | `@openclaw/document-extract-plugin` | contracts: documentExtractors | [document-extract](/uk/tools/pdf) | включено до OpenClaw |
|
||||
| duckduckgo | `@openclaw/duckduckgo-plugin` | contracts: webSearchProviders | [duckduckgo](/uk/tools/duckduckgo-search) | включено до OpenClaw |
|
||||
| elevenlabs | `@openclaw/elevenlabs-speech` | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders | [elevenlabs](/uk/providers/elevenlabs) | включено до OpenClaw |
|
||||
| exa | `@openclaw/exa-plugin` | contracts: webSearchProviders | [exa](/uk/tools/exa-search) | включено до OpenClaw |
|
||||
| fal | `@openclaw/fal-provider` | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders | [fal](/uk/providers/fal) | включено до OpenClaw |
|
||||
| file-transfer | `@openclaw/file-transfer` | contracts: tools | - | включено до OpenClaw |
|
||||
| firecrawl | `@openclaw/firecrawl-plugin` | contracts: tools, webFetchProviders, webSearchProviders | [firecrawl](/uk/tools/firecrawl) | включено до OpenClaw |
|
||||
| fireworks | `@openclaw/fireworks-provider` | providers: fireworks | [fireworks](/uk/providers/fireworks) | включено до OpenClaw |
|
||||
| github-copilot | `@openclaw/github-copilot-provider` | providers: github-copilot; contracts: memoryEmbeddingProviders | [github-copilot](/uk/providers/github-copilot) | включено до OpenClaw |
|
||||
| google | `@openclaw/google-plugin` | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders | [google](/uk/providers/google) | включено до OpenClaw |
|
||||
| gradium | `@openclaw/gradium-speech` | contracts: speechProviders | [gradium](/uk/providers/gradium) | включено до OpenClaw |
|
||||
| groq | `@openclaw/groq-provider` | providers: groq; contracts: mediaUnderstandingProviders | [groq](/uk/providers/groq) | включено до OpenClaw |
|
||||
| huggingface | `@openclaw/huggingface-provider` | providers: huggingface | [huggingface](/uk/providers/huggingface) | включено до OpenClaw |
|
||||
| imessage | `@openclaw/imessage` | channels: imessage | [imessage](/uk/channels/imessage) | включено до OpenClaw |
|
||||
| inworld | `@openclaw/inworld-speech` | contracts: speechProviders | [inworld](/uk/providers/inworld) | включено до OpenClaw |
|
||||
| irc | `@openclaw/irc` | channels: irc | [irc](/uk/channels/irc) | включено до OpenClaw |
|
||||
| kilocode | `@openclaw/kilocode-provider` | providers: kilocode | [kilocode](/uk/providers/kilocode) | включено до OpenClaw |
|
||||
| kimi | `@openclaw/kimi-provider` | providers: kimi, kimi-coding | [kimi](/uk/providers/moonshot) | включено до OpenClaw |
|
||||
| litellm | `@openclaw/litellm-provider` | providers: litellm; contracts: imageGenerationProviders | [litellm](/uk/providers/litellm) | включено до OpenClaw |
|
||||
| llm-task | `@openclaw/llm-task` | contracts: tools | - | включено до OpenClaw |
|
||||
| lmstudio | `@openclaw/lmstudio-provider` | providers: lmstudio; contracts: memoryEmbeddingProviders | [lmstudio](/uk/providers/lmstudio) | включено до OpenClaw |
|
||||
| memory-core | `@openclaw/memory-core` | contracts: memoryEmbeddingProviders, tools | - | включено до OpenClaw |
|
||||
| memory-wiki | `@openclaw/memory-wiki` | contracts: tools; skills | [memory-wiki](/uk/plugins/memory-wiki) | включено до OpenClaw |
|
||||
| microsoft | `@openclaw/microsoft-speech` | contracts: speechProviders | - | включено до OpenClaw |
|
||||
| microsoft-foundry | `@openclaw/microsoft-foundry` | providers: microsoft-foundry | - | включено до OpenClaw |
|
||||
| migrate-claude | `@openclaw/migrate-claude` | contracts: migrationProviders | - | включено до OpenClaw |
|
||||
| migrate-hermes | `@openclaw/migrate-hermes` | contracts: migrationProviders | - | включено до OpenClaw |
|
||||
| minimax | `@openclaw/minimax-provider` | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders | [minimax](/uk/providers/minimax) | включено до OpenClaw |
|
||||
| mistral | `@openclaw/mistral-provider` | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders | [mistral](/uk/providers/mistral) | включено до OpenClaw |
|
||||
| moonshot | `@openclaw/moonshot-provider` | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders | [moonshot](/uk/providers/moonshot) | включено до OpenClaw |
|
||||
| nvidia | `@openclaw/nvidia-provider` | providers: nvidia | [nvidia](/uk/providers/nvidia) | включено до OpenClaw |
|
||||
| ollama | `@openclaw/ollama-provider` | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders | [ollama](/uk/providers/ollama) | включено до OpenClaw |
|
||||
| open-prose | `@openclaw/open-prose` | skills | - | включено до OpenClaw |
|
||||
| openai | `@openclaw/openai-provider` | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders | [openai](/uk/providers/openai) | включено до OpenClaw |
|
||||
| opencode | `@openclaw/opencode-provider` | providers: opencode; contracts: mediaUnderstandingProviders | [opencode](/uk/providers/opencode) | включено до OpenClaw |
|
||||
| opencode-go | `@openclaw/opencode-go-provider` | providers: opencode-go; contracts: mediaUnderstandingProviders | [opencode-go](/uk/providers/opencode-go) | включено до OpenClaw |
|
||||
| openrouter | `@openclaw/openrouter-provider` | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders | [openrouter](/uk/providers/openrouter) | включено до OpenClaw |
|
||||
| openshell | `@openclaw/openshell-sandbox` | plugin | - | включено до OpenClaw |
|
||||
| perplexity | `@openclaw/perplexity-plugin` | contracts: webSearchProviders | [perplexity](/uk/tools/perplexity-search) | входить до OpenClaw |
|
||||
| qianfan | `@openclaw/qianfan-provider` | providers: qianfan | [qianfan](/uk/providers/qianfan) | входить до OpenClaw |
|
||||
| qwen | `@openclaw/qwen-provider` | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders | [qwen](/uk/providers/qwen) | входить до OpenClaw |
|
||||
| runway | `@openclaw/runway-provider` | contracts: videoGenerationProviders | [runway](/uk/providers/runway) | входить до OpenClaw |
|
||||
| searxng | `@openclaw/searxng-plugin` | contracts: webSearchProviders | - | входить до OpenClaw |
|
||||
| senseaudio | `@openclaw/senseaudio-provider` | contracts: mediaUnderstandingProviders | [senseaudio](/uk/providers/senseaudio) | входить до OpenClaw |
|
||||
| sglang | `@openclaw/sglang-provider` | providers: sglang | [sglang](/uk/providers/sglang) | входить до OpenClaw |
|
||||
| signal | `@openclaw/signal` | channels: signal | [signal](/uk/channels/signal) | входить до OpenClaw |
|
||||
| skill-workshop | `@openclaw/skill-workshop` | contracts: tools | [skill-workshop](/uk/plugins/skill-workshop) | входить до OpenClaw |
|
||||
| slack | `@openclaw/slack` | channels: slack | [slack](/uk/channels/slack) | входить до OpenClaw |
|
||||
| stepfun | `@openclaw/stepfun-provider` | providers: stepfun, stepfun-plan | [stepfun](/uk/providers/stepfun) | входить до OpenClaw |
|
||||
| synthetic | `@openclaw/synthetic-provider` | providers: synthetic | [synthetic](/uk/providers/synthetic) | входить до OpenClaw |
|
||||
| tavily | `@openclaw/tavily-plugin` | contracts: tools, webSearchProviders; skills | [tavily](/uk/tools/tavily) | входить до OpenClaw |
|
||||
| telegram | `@openclaw/telegram` | channels: telegram | [telegram](/uk/channels/telegram) | входить до OpenClaw |
|
||||
| tencent | `@openclaw/tencent-provider` | providers: tencent-tokenhub | [tencent](/uk/providers/tencent) | входить до OpenClaw |
|
||||
| together | `@openclaw/together-provider` | providers: together; contracts: videoGenerationProviders | [together](/uk/providers/together) | входить до OpenClaw |
|
||||
| tokenjuice | `@openclaw/tokenjuice` | contracts: agentToolResultMiddleware | [tokenjuice](/uk/tools/tokenjuice) | входить до OpenClaw |
|
||||
| tts-local-cli | `@openclaw/tts-local-cli` | contracts: speechProviders | - | входить до OpenClaw |
|
||||
| venice | `@openclaw/venice-provider` | providers: venice | [venice](/uk/providers/venice) | входить до OpenClaw |
|
||||
| vercel-ai-gateway | `@openclaw/vercel-ai-gateway-provider` | providers: vercel-ai-gateway | [vercel-ai-gateway](/uk/providers/vercel-ai-gateway) | входить до OpenClaw |
|
||||
| vllm | `@openclaw/vllm-provider` | providers: vllm | [vllm](/uk/providers/vllm) | входить до OpenClaw |
|
||||
| volcengine | `@openclaw/volcengine-provider` | providers: volcengine, volcengine-plan; contracts: speechProviders | [volcengine](/uk/providers/volcengine) | входить до OpenClaw |
|
||||
| voyage | `@openclaw/voyage-provider` | contracts: memoryEmbeddingProviders | - | входить до OpenClaw |
|
||||
| vydra | `@openclaw/vydra-provider` | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders | [vydra](/uk/providers/vydra) | входить до OpenClaw |
|
||||
| web-readability | `@openclaw/web-readability-plugin` | contracts: webContentExtractors | - | входить до OpenClaw |
|
||||
| webhooks | `@openclaw/webhooks` | plugin | [webhooks](/uk/plugins/webhooks) | входить до OpenClaw |
|
||||
| xai | `@openclaw/xai-plugin` | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders | [xai](/uk/providers/xai) | входить до OpenClaw |
|
||||
| xiaomi | `@openclaw/xiaomi-provider` | providers: xiaomi; contracts: speechProviders | [xiaomi](/uk/providers/xiaomi) | входить до OpenClaw |
|
||||
| zai | `@openclaw/zai-provider` | providers: zai; contracts: mediaUnderstandingProviders | [zai](/uk/providers/zai) | входить до OpenClaw |
|
||||
|
||||
## Офіційні зовнішні пакети
|
||||
|
||||
| Plugin | Пакет | Поверхня | Документація | Встановлення |
|
||||
| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| acpx | `@openclaw/acpx` | Skills | [acpx](/uk/tools/acp-agents-setup) | ClawHub + npm: `@openclaw/acpx` |
|
||||
| bluebubbles | `@openclaw/bluebubbles` | channels: bluebubbles | [bluebubbles](/uk/channels/bluebubbles) | ClawHub + npm: `@openclaw/bluebubbles` |
|
||||
| brave | `@openclaw/brave-plugin` | contracts: webSearchProviders | [brave](/uk/tools/brave-search) | ClawHub + npm: `@openclaw/brave-plugin` |
|
||||
| codex | `@openclaw/codex` | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders | [codex](/uk/plugins/codex-harness) | ClawHub + npm: `@openclaw/codex` |
|
||||
| diagnostics-otel | `@openclaw/diagnostics-otel` | Plugin | - | ClawHub + npm: `@openclaw/diagnostics-otel` |
|
||||
| diagnostics-prometheus | `@openclaw/diagnostics-prometheus` | Plugin | - | ClawHub + npm: `@openclaw/diagnostics-prometheus` |
|
||||
| diffs | `@openclaw/diffs` | contracts: tools; Skills | - | ClawHub + npm: `@openclaw/diffs` |
|
||||
| discord | `@openclaw/discord` | channels: discord | [discord](/uk/channels/discord) | ClawHub + npm: `@openclaw/discord` |
|
||||
| feishu | `@openclaw/feishu` | channels: feishu; contracts: tools; Skills | [feishu](/uk/channels/feishu) | ClawHub + npm: `@openclaw/feishu` |
|
||||
| google-meet | `@openclaw/google-meet` | contracts: tools | [google-meet](/uk/plugins/google-meet) | ClawHub + npm: `@openclaw/google-meet` |
|
||||
| googlechat | `@openclaw/googlechat` | channels: googlechat | [googlechat](/uk/channels/googlechat) | ClawHub + npm: `@openclaw/googlechat` |
|
||||
| line | `@openclaw/line` | channels: line | [line](/uk/channels/line) | ClawHub + npm: `@openclaw/line` |
|
||||
| lobster | `@openclaw/lobster` | contracts: tools | - | ClawHub + npm: `@openclaw/lobster` |
|
||||
| matrix | `@openclaw/matrix` | channels: matrix | [matrix](/uk/channels/matrix) | ClawHub + npm: `@openclaw/matrix` |
|
||||
| mattermost | `@openclaw/mattermost` | channels: mattermost | [mattermost](/uk/channels/mattermost) | ClawHub + npm: `@openclaw/mattermost` |
|
||||
| memory-lancedb | `@openclaw/memory-lancedb` | contracts: tools | [memory-lancedb](/uk/plugins/memory-lancedb) | ClawHub + npm: `@openclaw/memory-lancedb` |
|
||||
| msteams | `@openclaw/msteams` | channels: msteams | [msteams](/uk/channels/msteams) | ClawHub + npm: `@openclaw/msteams` |
|
||||
| nextcloud-talk | `@openclaw/nextcloud-talk` | channels: nextcloud-talk | [nextcloud-talk](/uk/channels/nextcloud-talk) | ClawHub + npm: `@openclaw/nextcloud-talk` |
|
||||
| nostr | `@openclaw/nostr` | channels: nostr | [nostr](/uk/channels/nostr) | ClawHub + npm: `@openclaw/nostr` |
|
||||
| qqbot | `@openclaw/qqbot` | channels: qqbot; contracts: tools; Skills | [qqbot](/uk/channels/qqbot) | ClawHub + npm: `@openclaw/qqbot` |
|
||||
| synology-chat | `@openclaw/synology-chat` | channels: synology-chat | [synology-chat](/uk/channels/synology-chat) | ClawHub + npm: `@openclaw/synology-chat` |
|
||||
| tlon | `@openclaw/tlon` | channels: tlon; contracts: tools; Skills | [tlon](/uk/channels/tlon) | ClawHub + npm: `@openclaw/tlon` |
|
||||
| twitch | `@openclaw/twitch` | channels: twitch | [twitch](/uk/channels/twitch) | ClawHub + npm: `@openclaw/twitch` |
|
||||
| voice-call | `@openclaw/voice-call` | contracts: tools | [voice-call](/uk/plugins/voice-call) | ClawHub + npm: `@openclaw/voice-call` |
|
||||
| whatsapp | `@openclaw/whatsapp` | channels: whatsapp | [whatsapp](/uk/channels/whatsapp) | ClawHub + npm: `@openclaw/whatsapp` |
|
||||
| zalo | `@openclaw/zalo` | channels: zalo | [zalo](/uk/channels/zalo) | ClawHub + npm: `@openclaw/zalo` |
|
||||
| zalouser | `@openclaw/zalouser` | channels: zalouser; contracts: tools | [zalouser](/uk/channels/zalouser), [zalouser](/uk/plugins/zalouser) | ClawHub + npm: `@openclaw/zalouser` |
|
||||
|
||||
## Лише checkout із вихідного коду
|
||||
|
||||
| Plugin | Пакет | Поверхня | Документація | Встановлення |
|
||||
| ---------- | ---------------------- | -------------------- | ---------------------------------- | -------------------- |
|
||||
| qa-channel | `@openclaw/qa-channel` | channels: qa-channel | [qa-channel](/uk/channels/qa-channel) | лише checkout із вихідного коду |
|
||||
| qa-lab | `@openclaw/qa-lab` | Plugin | - | лише checkout із вихідного коду |
|
||||
| qa-matrix | `@openclaw/qa-matrix` | Plugin | - | лише checkout із вихідного коду |
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії
|
||||
- Ви налаштовуєте або розробляєте Plugin голосових викликів
|
||||
- Вам потрібен голос у реальному часі або потокова транскрипція в телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційною голосовою взаємодією в реальному часі та потоковою транскрипцією
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційним голосом у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T07:52:42Z"
|
||||
generated_at: "2026-05-02T09:29:40Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fc27646aca94c88d50d42838e166ac81eba3373154797cbb564e9c2eab0533fa
|
||||
source_hash: 8f04b14ad1aafcc6036aff2301d9d0210c0cde333051ed89d498c51b4e0c0353
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Voice calls for OpenClaw через Plugin. Підтримує вихідні сповіщення,
|
||||
Голосові виклики для OpenClaw через plugin. Підтримує вихідні сповіщення,
|
||||
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками allowlist.
|
||||
|
||||
@ -24,7 +24,7 @@ Voice calls for OpenClaw через Plugin. Підтримує вихідні с
|
||||
speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
Plugin Voice Call працює **усередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте plugin на машині, де працює
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
</Note>
|
||||
@ -32,14 +32,14 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Install the plugin">
|
||||
<Step title="Установіть plugin">
|
||||
<Tabs>
|
||||
<Tab title="From npm">
|
||||
<Tab title="З npm">
|
||||
```bash
|
||||
openclaw plugins install @openclaw/voice-call
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="From a local folder (dev)">
|
||||
<Tab title="З локальної папки (розробка)">
|
||||
```bash
|
||||
PLUGIN_SRC=./path/to/local/voice-call-plugin
|
||||
openclaw plugins install "$PLUGIN_SRC"
|
||||
@ -48,39 +48,38 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія
|
||||
пакета походить зі старішої зовнішньої гілки пакування; використовуйте
|
||||
поточну пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде
|
||||
опубліковано новіший npm-пакет.
|
||||
Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку
|
||||
OpenClaw або шлях до локальної папки, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
Після цього перезапустіть Gateway, щоб plugin завантажився.
|
||||
|
||||
</Step>
|
||||
<Step title="Configure provider and webhook">
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну форму див.
|
||||
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
|
||||
<Step title="Налаштуйте провайдера й webhook">
|
||||
Установіть конфігурацію в `plugins.entries.voice-call.config` (див.
|
||||
[Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і публічно
|
||||
доступний URL Webhook.
|
||||
доступний URL webhook.
|
||||
</Step>
|
||||
<Step title="Verify setup">
|
||||
<Step title="Перевірте налаштування">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє,
|
||||
чи plugin увімкнений, облікові дані провайдера, доступність Webhook і те,
|
||||
Типовий вивід зручний для читання в журналах чату й терміналах. Він перевіряє
|
||||
увімкнення plugin, облікові дані провайдера, доступність webhook, а також те,
|
||||
що активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
`--json` для скриптів.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke test">
|
||||
<Step title="Smoke-тест">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Обидві команди за замовчуванням виконують пробний запуск. Додайте `--yes`,
|
||||
щоб фактично здійснити короткий вихідний виклик-сповіщення:
|
||||
Обидві команди за замовчуванням виконують пробний запуск без реального виклику. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний виклик-сповіщення:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -90,23 +89,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначати **публічний URL Webhook**.
|
||||
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний serve-варіант
|
||||
визначається як loopback чи приватний мережевий простір, налаштування
|
||||
завершується помилкою замість запуску провайдера, який не зможе отримувати
|
||||
Webhook від операторів.
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічний URL webhook**.
|
||||
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
|
||||
визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати carrier webhooks.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з
|
||||
відсутніми ключами та пропускає запуск runtime. Команди, RPC-виклики й
|
||||
інструменти агента все одно повертають точну відсутню конфігурацію провайдера
|
||||
під час використання.
|
||||
під час запуску Gateway у журнал записується попередження setup-incomplete з відсутніми ключами, і
|
||||
runtime не запускається. Команди, RPC-виклики та інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
|
||||
<Note>
|
||||
Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Облікові дані voice-call підтримують SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -120,6 +117,17 @@ Webhook від операторів.
|
||||
fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
|
||||
toNumber: "+15550005678",
|
||||
sessionScope: "per-phone", // per-phone | per-call
|
||||
numbers: {
|
||||
"+15550009999": {
|
||||
inboundGreeting: "Silver Fox Cards, how can I help?",
|
||||
responseSystemPrompt: "You are a concise baseball card specialist.",
|
||||
tts: {
|
||||
providers: {
|
||||
openai: { voice: "alloy" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
twilio: {
|
||||
accountSid: "ACxxxxxxxx",
|
||||
@ -168,28 +176,28 @@ Webhook від операторів.
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- Twilio, Telnyx і Plivo всі потребують **публічно доступного** URL Webhook.
|
||||
<Accordion title="Нотатки щодо доступності провайдера та безпеки">
|
||||
- Twilio, Telnyx і Plivo вимагають **публічно доступного** URL webhook.
|
||||
- `mock` — локальний dev-провайдер (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
|
||||
- `skipSignatureVerification` призначено лише для локального тестування.
|
||||
- На безкоштовному рівні ngrok задайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусова.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL безкоштовного рівня ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для production надавайте перевагу стабільному домену або funnel Tailscale.
|
||||
- Telnyx вимагає `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
|
||||
- `skipSignatureVerification` призначений лише для локального тестування.
|
||||
- На безкоштовному рівні ngrok установіть `publicUrl` у точний URL ngrok; перевірка підпису завжди примусово застосовується.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Twilio webhooks з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL безкоштовного рівня Ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміститься, підписи Twilio не пройдуть перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Streaming connection caps">
|
||||
<Accordion title="Ліміти потокових підключень">
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих pre-start сокетів на IP-адресу джерела.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (pending + active).
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети до старту для кожної вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Legacy config migrations">
|
||||
Старіші конфігурації, які використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
<Accordion title="Міграції застарілої конфігурації">
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Runtime fallback поки що все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — `openclaw doctor --fix`, а compat shim є
|
||||
Runtime fallback поки що приймає старі ключі voice-call, але
|
||||
шлях переписування — це `openclaw doctor --fix`, а сумісний shim є
|
||||
тимчасовим.
|
||||
|
||||
Автоматично мігровані ключі streaming:
|
||||
@ -205,16 +213,16 @@ Webhook від операторів.
|
||||
|
||||
## Область сесії
|
||||
|
||||
За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, тож
|
||||
повторні виклики від того самого абонента зберігають пам’ять розмови. Задайте
|
||||
`sessionScope: "per-call"`, коли кожен операторський виклик має починатися зі
|
||||
свіжим контекстом, наприклад для рецепції, бронювання, IVR або потоків мосту
|
||||
Google Meet, де той самий номер телефону може представляти різні зустрічі.
|
||||
За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, щоб повторні виклики від
|
||||
того самого абонента зберігали пам’ять розмови. Установіть `sessionScope: "per-call"`, коли
|
||||
кожен carrier call має починатися зі свіжого контексту, наприклад для рецепції,
|
||||
бронювання, IVR або bridge-потоків Google Meet, де той самий номер телефону може
|
||||
представляти різні зустрічі.
|
||||
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає повнодуплексного голосового провайдера реального часу для
|
||||
живого аудіо виклику. Це окремо від `streaming`, який лише передає аудіо
|
||||
`realtime` вибирає провайдера повнодуплексного голосу в реальному часі для live call
|
||||
audio. Це окремо від `streaming`, який лише пересилає аудіо
|
||||
провайдерам транскрипції в реальному часі.
|
||||
|
||||
<Warning>
|
||||
@ -225,25 +233,25 @@ Google Meet, де той самий номер телефону може пре
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `realtime.enabled` підтримується для Twilio Media Streams.
|
||||
- `realtime.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу.
|
||||
- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider plugins.
|
||||
- `realtime.provider` необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
|
||||
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider plugins.
|
||||
- Сира конфігурація, якою володіє провайдер, розміщується в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw.
|
||||
- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає проіндексовану пам’ять/контекст сесії для запитання consult і повертає ці фрагменти моделі реального часу в межах `realtime.fastContext.timeoutMs`, перш ніж переходити до повного consult agent лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного голосового провайдера реального часу, Voice Call записує попередження й пропускає realtime media замість того, щоб зупиняти весь plugin.
|
||||
- Ключі сесії consult повторно використовують збережену сесію виклику, коли вона доступна, а потім повертаються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих викликів).
|
||||
- Voice Call за замовчуванням надає спільний realtime-інструмент `openclaw_agent_consult`. Модель realtime може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає індексовану пам’ять/контекст сесії для consult-запитання й повертає ці фрагменти realtime-моделі в межах `realtime.fastContext.timeoutMs`, перш ніж повертатися до повного consult-агента лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жоден провайдер голосу в реальному часі взагалі не зареєстрований, Voice Call записує попередження в журнал і пропускає realtime media замість того, щоб завершити роботу всього plugin з помилкою.
|
||||
- Ключі consult-сесії повторно використовують збережену сесію виклику, коли вона доступна, а потім повертаються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих викликів).
|
||||
|
||||
### Політика інструментів
|
||||
|
||||
`realtime.toolPolicy` керує запуском consult:
|
||||
`realtime.toolPolicy` керує consult-запуском:
|
||||
|
||||
| Політика | Поведінка |
|
||||
| Політика | Поведінка |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати стандартну політику інструментів агента. |
|
||||
| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` все одно передаються провайдеру реального часу. |
|
||||
| `safe-read-only` | Надає consult-інструмент і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Надає consult-інструмент і дозволяє звичайному агенту використовувати нормальну політику інструментів агента. |
|
||||
| `none` | Не надає consult-інструмент. Користувацькі `realtime.tools` усе одно передаються провайдеру realtime. |
|
||||
|
||||
### Приклади провайдерів реального часу
|
||||
### Приклади провайдерів realtime
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
@ -304,23 +312,22 @@ Google Meet, де той самий номер телефону може пре
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдер Google](/uk/providers/google) і
|
||||
[провайдер OpenAI](/uk/providers/openai), щоб переглянути специфічні для провайдера
|
||||
параметри голосу реального часу.
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai) для специфічних для провайдера опцій голосу realtime.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для live call audio.
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `streaming.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрибування в реальному часі.
|
||||
- Вбудовані провайдери транскрибування в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми провайдерськими plugins.
|
||||
- Необроблена конфігурація, якою володіє провайдер, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення `start` для потоку, Voice Call негайно реєструє потік, ставить вхідні медіадані в чергу через провайдера транскрибування, доки провайдер підключається, і запускає початкове привітання лише після готовності транскрибування в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жоден провайдер не зареєстрований, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб спричинити збій усього plugin.
|
||||
- `streaming.provider` необов'язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого постачальника транскрипції в реальному часі.
|
||||
- Вбудовані постачальники транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми provider plugins.
|
||||
- Сира конфігурація, що належить постачальнику, зберігається в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через постачальника транскрипції, поки постачальник підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого постачальника або жодного постачальника не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб спричинити збій усього Plugin.
|
||||
|
||||
### Приклади провайдерів потокового передавання
|
||||
### Приклади постачальників потокового передавання
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenAI">
|
||||
@ -391,8 +398,8 @@ Google Meet, де той самий номер телефону може пре
|
||||
## TTS для викликів
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації plugin з
|
||||
**такою самою структурою** — вона глибоко об’єднується з `messages.tts`.
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації Plugin з
|
||||
**такою самою формою** — вона глибоко зливається з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -409,17 +416,17 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонне аудіо потребує PCM;
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM;
|
||||
поточний транспорт Microsoft не надає телефонний PCM-вивід.
|
||||
</Warning>
|
||||
|
||||
Нотатки щодо поведінки:
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до нативних голосів провайдера.
|
||||
- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML `<Say>`. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується з помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли телефонний TTS повертається до резервного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
|
||||
- Коли barge-in Twilio або завершення потоку очищає чергу очікування TTS, запити відтворення в черзі завершуються, а не залишають абонентів у завислому стані в очікуванні завершення відтворення.
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована в репозиторії конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до нативних голосів постачальника.
|
||||
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли телефонний TTS повертається до вторинного постачальника, Voice Call записує попередження з ланцюжком постачальників (`from`, `to`, `attempts`) для налагодження.
|
||||
- Коли втручання Twilio або демонтаж потоку очищає чергу TTS, запити на відтворення в черзі завершуються замість того, щоб залишати абонентів у стані очікування завершення відтворення.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
@ -462,7 +469,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке об’єднання)">
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке злиття)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -499,64 +506,110 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller-ID з низьким рівнем гарантії.
|
||||
Plugin нормалізує надане провайдером значення `From` і порівнює його з
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і
|
||||
цілісність payload, але вона **не** доводить володіння номером абонента
|
||||
PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller-ID, а не як надійну
|
||||
ідентифікацію абонента.
|
||||
`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низькою гарантією. Plugin нормалізує надане постачальником значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку постачальником і цілісність корисного навантаження, але **не** доводить володіння номером абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію за caller ID, а не як надійну ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують агентну систему. Налаштовуйте за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Контракт мовленнєвого виводу
|
||||
### Маршрутизація за номером
|
||||
|
||||
Для автовідповідей Voice Call додає до системного prompt строгий контракт
|
||||
мовленнєвого виводу:
|
||||
Використовуйте `numbers`, коли один Voice Call plugin приймає виклики для кількох телефонних
|
||||
номерів і кожен номер має поводитися як окрема лінія. Наприклад, один
|
||||
номер може використовувати невимушеного персонального помічника, а інший — бізнес-
|
||||
персону, іншого агента відповіді та інший голос TTS.
|
||||
|
||||
Маршрути вибираються з наданого постачальником набраного номера `To`. Ключі мають бути
|
||||
номерами E.164. Коли надходить виклик, Voice Call один раз визначає відповідний маршрут,
|
||||
зберігає зіставлений маршрут у записі виклику та повторно використовує цю ефективну конфігурацію
|
||||
для привітання, класичного шляху автовідповіді, шляху консультації в реальному часі та
|
||||
відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальна конфігурація Voice Call.
|
||||
Вихідні виклики не використовують `numbers`; передавайте вихідну ціль, повідомлення та
|
||||
сеанс явно під час ініціювання виклику.
|
||||
|
||||
Перевизначення маршрутів наразі підтримують:
|
||||
|
||||
- `inboundGreeting`
|
||||
- `tts`
|
||||
- `agentId`
|
||||
- `responseModel`
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
Значення маршруту `tts` глибоко зливається поверх глобальної конфігурації Voice Call `tts`, тож
|
||||
зазвичай можна перевизначити лише голос постачальника:
|
||||
|
||||
```json5
|
||||
{
|
||||
inboundGreeting: "Hello from the main line.",
|
||||
responseSystemPrompt: "You are the default voice assistant.",
|
||||
tts: {
|
||||
provider: "openai",
|
||||
providers: {
|
||||
openai: { voice: "coral" },
|
||||
},
|
||||
},
|
||||
numbers: {
|
||||
"+15550001111": {
|
||||
inboundGreeting: "Silver Fox Cards, how can I help?",
|
||||
responseSystemPrompt: "You are a concise baseball card specialist.",
|
||||
tts: {
|
||||
providers: {
|
||||
openai: { voice: "alloy" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Контракт мовленого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає строгий контракт мовленого виводу до
|
||||
системного prompt:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
```
|
||||
|
||||
Voice Call обережно витягує текст мовлення:
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує payload, позначені як вміст reasoning/error.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням або метаданими.
|
||||
- Ігнорує корисні навантаження, позначені як вміст reasoning/помилки.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаопису.
|
||||
|
||||
Це утримує мовленнєве відтворення зосередженим на тексті для абонента й запобігає
|
||||
Це зосереджує мовлене відтворення на тексті для абонента й запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до
|
||||
поточного стану відтворення:
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного
|
||||
стану відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується з помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio починається під час підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворене.
|
||||
- Голосові розмови в реальному часі використовують власний початковий хід потоку в реальному часі. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сесії `<Connect><Stream>` залишаються приєднаними.
|
||||
- Очищення черги через втручання й автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio запускається під час підключення потоку без додаткової затримки.
|
||||
- Втручання перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено.
|
||||
- Голосові розмови в реальному часі використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються приєднаними.
|
||||
|
||||
### Пільговий період відключення потоку Twilio
|
||||
### Пільговий період від'єднання потоку Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call очікує **2000 ms** перед
|
||||
Коли медіапотік Twilio від'єднується, Voice Call чекає **2000 мс** перед
|
||||
автоматичним завершенням виклику:
|
||||
|
||||
- Якщо потік повторно підключається впродовж цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
|
||||
## Очищення застарілих викликів
|
||||
## Прибирач застарілих викликів
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний
|
||||
webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, що ніколи не завершуються). Типове значення
|
||||
— `0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі сповіщення.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -575,26 +628,26 @@ webhook (наприклад, виклики в режимі сповіщення
|
||||
|
||||
## Безпека Webhook
|
||||
|
||||
Коли proxy або tunnel розташований перед Gateway, plugin
|
||||
відтворює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
контролюють, яким forwarded headers довіряти:
|
||||
Коли перед Gateway стоїть проксі або тунель, Plugin
|
||||
реконструює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
керують тим, яким forwarded-заголовкам довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Список дозволених хостів із forwarding headers.
|
||||
Список дозволених хостів із forwarding-заголовків.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряти forwarded headers без списку дозволених.
|
||||
Довіряти forwarded-заголовкам без списку дозволених.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряти forwarded headers лише тоді, коли remote IP запиту відповідає списку.
|
||||
Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
|
||||
</ParamField>
|
||||
|
||||
Додаткові захисти:
|
||||
Додатковий захист:
|
||||
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні webhook-запити підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен на кожен хід у callbacks `<Gather>`, тому застарілі або повторно відтворені callbacks мовлення не можуть задовольнити новіший очікуваний хід transcript.
|
||||
- Неавтентифіковані webhook-запити відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера.
|
||||
- Webhook voice-call використовує спільний pre-auth профіль тіла (64 KB / 5 секунд) плюс per-IP ліміт одночасних запитів до перевірки підпису.
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені чинні webhook-запити підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах `<Gather>`, тому застарілі/повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипту.
|
||||
- Неавтентифіковані webhook-запити відхиляються до читання тіла, коли відсутні обов'язкові signature-заголовки постачальника.
|
||||
- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису.
|
||||
|
||||
Приклад зі стабільним публічним хостом:
|
||||
|
||||
@ -631,14 +684,14 @@ openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Коли Gateway уже запущено, операційні команди `voicecall` делегуються
|
||||
runtime голосових викликів, яким володіє Gateway, щоб CLI не прив’язував другий
|
||||
voice-call runtime, що належить Gateway, щоб CLI не прив'язував другий
|
||||
webhook-сервер. Якщо Gateway недоступний, команди повертаються до
|
||||
автономного CLI runtime.
|
||||
самостійного CLI runtime.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
|
||||
Використовуйте `--file <path>`, щоб вказати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
|
||||
для затримки ходу й часу очікування прослуховування.
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call.
|
||||
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (за замовчуванням 200). Вивід містить p50/p90/p99
|
||||
для затримки ходу та часу очікування слухання.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
@ -653,11 +706,11 @@ webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
Цей repo постачає відповідний документ skill за шляхом `skills/voice-call/SKILL.md`.
|
||||
Цей репозиторій постачається з відповідним документом Skills за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## Gateway RPC
|
||||
|
||||
| Метод | Аргументи |
|
||||
| Метод | Аргументи |
|
||||
| -------------------- | ------------------------------------------ |
|
||||
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
|
||||
| `voicecall.continue` | `callId`, `message` |
|
||||
@ -666,13 +719,13 @@ webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі сповіщення
|
||||
`dtmfSequence` чинний лише з `mode: "conversation"`. Виклики в режимі сповіщення
|
||||
мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні
|
||||
цифри після підключення.
|
||||
цифри після з’єднання.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
### Налаштування не може виставити Webhook
|
||||
### Налаштування не проходить через доступність webhook
|
||||
|
||||
Запустіть налаштування з того самого середовища, у якому працює Gateway:
|
||||
|
||||
@ -681,11 +734,19 @@ openclaw voicecall setup
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований `publicUrl` усе одно завершується помилкою, коли він указує на локальний або приватний мережевий простір, оскільки оператор не може виконати зворотний виклик на ці адреси. Не використовуйте `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`.
|
||||
Для `twilio`, `telnyx` і `plivo` стан `webhook-exposure` має бути зеленим. Налаштований
|
||||
`publicUrl` усе одно не проходить перевірку, якщо він указує на локальний або приватний мережевий
|
||||
простір, оскільки оператор не може виконати зворотний виклик на ці адреси. Не використовуйте
|
||||
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
|
||||
`192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`.
|
||||
|
||||
Вихідні дзвінки Twilio у режимі сповіщень надсилають початковий `<Say>` TwiML безпосередньо в запиті створення дзвінка, тому перше озвучене повідомлення не залежить від того, чи Twilio отримає webhook TwiML. Публічний webhook усе ще потрібен для зворотних викликів стану, розмовних дзвінків, DTMF перед з’єднанням, потоків реального часу та керування дзвінком після з’єднання.
|
||||
Вихідні виклики Twilio в режимі сповіщення надсилають початковий `<Say>` TwiML безпосередньо в
|
||||
запиті створення виклику, тому перше промовлене повідомлення не залежить від того, чи Twilio
|
||||
отримає webhook TwiML. Публічний webhook усе одно потрібен для зворотних викликів стану,
|
||||
розмовних викликів, DTMF до з’єднання, потоків у реальному часі та керування викликом
|
||||
після з’єднання.
|
||||
|
||||
Використайте один шлях публічної доступності:
|
||||
Використовуйте один шлях публічного доступу:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -712,19 +773,23 @@ openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` виконує пробний запуск, якщо не передати `--yes`.
|
||||
`voicecall smoke` є пробним запуском, якщо не передати `--yes`.
|
||||
|
||||
### Облікові дані провайдера не працюють
|
||||
### Облікові дані провайдера не проходять перевірку
|
||||
|
||||
Перевірте вибраного провайдера та обов’язкові поля облікових даних:
|
||||
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber`, або `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`.
|
||||
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` і `fromNumber`.
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber` або
|
||||
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`.
|
||||
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` і
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`.
|
||||
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє середовище.
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє
|
||||
середовище.
|
||||
|
||||
### Дзвінки запускаються, але webhook провайдера не надходять
|
||||
### Виклики починаються, але webhook-и провайдера не надходять
|
||||
|
||||
Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу webhook:
|
||||
|
||||
@ -732,7 +797,7 @@ openclaw voicecall smoke
|
||||
https://voice.example.com/voice/webhook
|
||||
```
|
||||
|
||||
Потім перегляньте стан виконання:
|
||||
Потім перевірте стан виконання:
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
@ -743,23 +808,30 @@ openclaw logs --follow
|
||||
Поширені причини:
|
||||
|
||||
- `publicUrl` указує на інший шлях, ніж `serve.path`.
|
||||
- URL тунелю змінився після запуску Gateway.
|
||||
- URL тунелю змінилася після запуску Gateway.
|
||||
- Проксі пересилає запит, але видаляє або переписує заголовки host/proto.
|
||||
- Брандмауер або DNS спрямовує публічне ім’я хоста не на Gateway.
|
||||
- Брандмауер або DNS спрямовує публічне ім’я хоста кудись, окрім Gateway.
|
||||
- Gateway було перезапущено без увімкненого Plugin Voice Call.
|
||||
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, установіть `webhookSecurity.allowedHosts` на публічне ім’я хоста або використайте `webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте `webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під вашим контролем.
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, задайте
|
||||
`webhookSecurity.allowedHosts` як публічне ім’я хоста або використовуйте
|
||||
`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте
|
||||
`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває
|
||||
під вашим контролем.
|
||||
|
||||
### Перевірка підпису не проходить
|
||||
|
||||
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює з вхідного запиту. Якщо підписи не проходять перевірку:
|
||||
Підписи провайдера перевіряються за публічною URL-адресою, яку OpenClaw відтворює
|
||||
з вхідного запиту. Якщо перевірка підписів не проходить:
|
||||
|
||||
- Переконайтеся, що URL webhook у провайдера точно збігається з `publicUrl`, включно зі схемою, хостом і шляхом.
|
||||
- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли ім’я хоста тунелю змінюється.
|
||||
- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте `webhookSecurity.allowedHosts`.
|
||||
- Переконайтеся, що URL webhook провайдера точно збігається з `publicUrl`, включно зі
|
||||
схемою, хостом і шляхом.
|
||||
- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю.
|
||||
- Переконайтеся, що проксі зберігає оригінальні заголовки host і proto, або налаштуйте
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- Не вмикайте `skipSignatureVerification` поза локальним тестуванням.
|
||||
|
||||
### Приєднання Google Meet через Twilio не працює
|
||||
### Не вдається приєднатися до Google Meet через Twilio
|
||||
|
||||
Google Meet використовує цей Plugin для приєднання через телефонний набір Twilio. Спочатку перевірте Voice Call:
|
||||
|
||||
@ -774,33 +846,43 @@ openclaw voicecall smoke --to "+15555550123"
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Якщо Voice Call має зелений статус, але учасник Meet так і не приєднується, перевірте номер для телефонного підключення Meet, PIN і `--dtmf-sequence`. Телефонний дзвінок може бути справним, тоді як зустріч відхиляє або ігнорує неправильну послідовність DTMF.
|
||||
Якщо Voice Call має зелений стан, але учасник Meet так і не приєднується, перевірте номер
|
||||
для телефонного підключення Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
|
||||
зустріч відхиляє або ігнорує неправильну DTMF-послідовність.
|
||||
|
||||
Google Meet передає послідовність DTMF Meet і вступний текст у `voicecall.start`. Для дзвінків Twilio Voice Call спочатку обслуговує DTMF TwiML, перенаправляє назад на webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ було згенеровано після приєднання телефонного учасника до зустрічі.
|
||||
Google Meet передає DTMF-послідовність Meet і вступний текст у `voicecall.start`.
|
||||
Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, переспрямовує назад до
|
||||
webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ генерувався
|
||||
після того, як телефонний учасник приєднався до зустрічі.
|
||||
|
||||
Використовуйте `openclaw logs --follow` для трасування фази в реальному часі. Справне приєднання Twilio Meet записує такий порядок:
|
||||
Використовуйте `openclaw logs --follow` для живого трасування фази. Справне приєднання Twilio Meet
|
||||
реєструє такий порядок:
|
||||
|
||||
- Google Meet делегує приєднання Twilio до Voice Call.
|
||||
- Voice Call зберігає DTMF TwiML перед з’єднанням.
|
||||
- Початковий TwiML Twilio споживається й обслуговується перед обробкою в реальному часі.
|
||||
- Voice Call обслуговує TwiML реального часу для дзвінка Twilio.
|
||||
- Міст реального часу запускається з поставленим у чергу початковим привітанням.
|
||||
- Voice Call зберігає DTMF TwiML до з’єднання.
|
||||
- Початковий TwiML Twilio споживається й віддається перед обробкою в реальному часі.
|
||||
- Voice Call віддає TwiML реального часу для виклику Twilio.
|
||||
- Міст реального часу запускається з початковим привітанням у черзі.
|
||||
|
||||
`openclaw voicecall tail` усе ще показує збережені записи дзвінків; це корисно для стану дзвінка й транскриптів, але не кожен перехід webhook або реального часу з’являється там.
|
||||
`openclaw voicecall tail` усе ще показує збережені записи викликів; це корисно для
|
||||
стану виклику й транскриптів, але не кожен webhook-перехід або перехід реального часу
|
||||
там з’являється.
|
||||
|
||||
### У дзвінку реального часу немає мовлення
|
||||
### Виклик у реальному часі не має мовлення
|
||||
|
||||
Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно мати значення true.
|
||||
Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно бути true.
|
||||
|
||||
Для дзвінків Twilio у реальному часі також перевірте:
|
||||
Для викликів Twilio у реальному часі також перевірте:
|
||||
|
||||
- Plugin провайдера реального часу завантажено й зареєстровано.
|
||||
- `realtime.provider` не встановлено або вказує на зареєстрованого провайдера.
|
||||
- Ключ API провайдера доступний процесу Gateway.
|
||||
- `openclaw logs --follow` показує, що TwiML реального часу обслуговується, міст реального часу запущено, а початкове привітання поставлено в чергу.
|
||||
- Plugin провайдера реального часу завантажено та зареєстровано.
|
||||
- `realtime.provider` не задано або він називає зареєстрованого провайдера.
|
||||
- API-ключ провайдера доступний процесу Gateway.
|
||||
- `openclaw logs --follow` показує, що TwiML реального часу віддано, міст реального часу
|
||||
запущено, а початкове привітання поставлено в чергу.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Перетворення тексту на мовлення](/uk/tools/tts)
|
||||
- [Синтез мовлення](/uk/tools/tts)
|
||||
- [Голосове пробудження](/uk/nodes/voicewake)
|
||||
|
||||
@ -3,40 +3,40 @@ read_when:
|
||||
- Використання або налаштування чат-команд
|
||||
- Налагодження маршрутизації команд або дозволів
|
||||
sidebarTitle: Slash commands
|
||||
summary: 'Слеш-команди: текстові проти нативних, конфігурація та підтримувані команди'
|
||||
summary: 'Слеш-команди: текстові й нативні, конфігурація та підтримувані команди'
|
||||
title: Слеш-команди
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T02:49:16Z"
|
||||
generated_at: "2026-05-02T09:29:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 00a00619cc0eff25b81b475eab5b0b3d808bf067e6e004a491a90ec3982149b7
|
||||
source_hash: b469c4436dec92eb3712f71e5f54bf2c96b9b0b17d60a1533d8669c127caefee
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Команди обробляє Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. Команда bash-чату лише для хоста використовує `! <cmd>` (з `/bash <cmd>` як псевдонімом).
|
||||
|
||||
Коли розмову або гілку прив’язано до ACP-сесії, звичайний подальший текст спрямовується до цього ACP harness. Команди керування Gateway усе одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд OpenClaw ACP, а `/status` і `/unfocus` залишаються локальними, коли для цієї поверхні ввімкнено обробку команд.
|
||||
Коли розмову або тред прив’язано до сесії ACP, звичайний текст подальших повідомлень спрямовується до цього ACP harness. Команди керування Gateway все одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд ACP OpenClaw, а `/status` і `/unfocus` залишаються локальними щоразу, коли для поверхні ввімкнено обробку команд.
|
||||
|
||||
Є дві пов’язані системи:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Commands">
|
||||
<Accordion title="Команди">
|
||||
Окремі повідомлення `/...`.
|
||||
</Accordion>
|
||||
<Accordion title="Directives">
|
||||
<Accordion title="Директиви">
|
||||
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
|
||||
- Directives вилучаються з повідомлення до того, як модель його побачить.
|
||||
- У звичайних повідомленнях чату (не лише з directives) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії.
|
||||
- У повідомленнях лише з directives (повідомлення містить тільки directives) вони зберігаються в сесії й відповідають підтвердженням.
|
||||
- Directives застосовуються лише для **авторизованих відправників**. Якщо встановлено `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація походить зі списків дозволених каналу/сполучення плюс `commands.useAccessGroups`. Неавторизовані відправники бачать directives як звичайний текст.
|
||||
- Директиви вилучаються з повідомлення до того, як його побачить модель.
|
||||
- У звичайних повідомленнях чату (не лише з директивами) вони розглядаються як "вбудовані підказки" і **не** зберігають налаштування сесії.
|
||||
- У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження.
|
||||
- Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація надходить зі списків дозволених/спарювання каналу плюс `commands.useAccessGroups`. Для неавторизованих відправників директиви розглядаються як звичайний текст.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Inline shortcuts">
|
||||
Лише відправники зі списку дозволених/авторизовані: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
<Accordion title="Вбудовані скорочення">
|
||||
Лише для відправників зі списку дозволених/авторизованих: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
|
||||
Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним потоком.
|
||||
Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайний потік.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -69,104 +69,105 @@ x-i18n:
|
||||
```
|
||||
|
||||
<ParamField path="commands.text" type="boolean" default="true">
|
||||
Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення на `false`.
|
||||
Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди працюють навіть якщо встановити це значення на `false`.
|
||||
</ParamField>
|
||||
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
|
||||
Реєструє нативні команди. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash commands); ігнорується для провайдерів без нативної підтримки. Установіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (bool або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Командами Slack керують у застосунку Slack, і вони не видаляються автоматично.
|
||||
Реєструє нативні команди. Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash-команди); ігнорується для провайдерів без нативної підтримки. Задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (bool або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Командами Slack керують у застосунку Slack, і вони не видаляються автоматично.
|
||||
</ParamField>
|
||||
У Discord специфікації нативних команд можуть містити `descriptionLocalizations`, які OpenClaw публікує як Discord `description_localizations` і включає до порівнянь узгодження.
|
||||
У Discord специфікації нативних команд можуть містити `descriptionLocalizations`, які OpenClaw публікує як Discord `description_localizations` і включає в порівняння узгодження.
|
||||
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
|
||||
Реєструє команди **skill** нативно, коли це підтримується. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash command для кожного skill). Установіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (bool або `"auto"`).
|
||||
Реєструє команди **skill** нативно, коли це підтримується. Auto: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash-команди для кожного skill). Задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (bool або `"auto"`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.bash" type="boolean" default="false">
|
||||
Вмикає `! <cmd>` для запуску команд оболонки хоста (`/bash <cmd>` є псевдонімом; потрібні списки дозволених `tools.elevated`).
|
||||
Вмикає `! <cmd>` для запуску команд оболонки хоста (`/bash <cmd>` є псевдонімом; потребує списків дозволених `tools.elevated`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
|
||||
Керує тим, як довго bash очікує перед переходом у фоновий режим (`0` одразу переводить у фон).
|
||||
Керує тим, як довго bash очікує перед перемиканням у фоновий режим (`0` одразу переводить у фон).
|
||||
</ParamField>
|
||||
<ParamField path="commands.config" type="boolean" default="false">
|
||||
Вмикає `/config` (читає/записує `openclaw.json`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.mcp" type="boolean" default="false">
|
||||
Вмикає `/mcp` (читає/записує MCP-конфігурацію, керовану OpenClaw, у `mcp.servers`).
|
||||
Вмикає `/mcp` (читає/записує керовану OpenClaw конфігурацію MCP у `mcp.servers`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.plugins" type="boolean" default="false">
|
||||
Вмикає `/plugins` (виявлення/статус plugin, а також елементи керування встановленням і ввімкненням/вимкненням).
|
||||
Вмикає `/plugins` (виявлення/статус Plugin плюс елементи керування встановленням і ввімкненням/вимкненням).
|
||||
</ParamField>
|
||||
<ParamField path="commands.debug" type="boolean" default="false">
|
||||
Вмикає `/debug` (лише runtime-перевизначення).
|
||||
Вмикає `/debug` (перевизначення лише під час виконання).
|
||||
</ParamField>
|
||||
<ParamField path="commands.restart" type="boolean" default="true">
|
||||
Вмикає `/restart` плюс дії інструментів перезапуску Gateway.
|
||||
Вмикає `/restart` плюс дії інструментів перезапуску gateway.
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerAllowFrom" type="string[]">
|
||||
Задає явний список дозволених власника для командних/інструментальних поверхонь лише для власника. Це обліковий запис людини-оператора, який може схвалювати небезпечні дії та запускати команди, як-от `/diagnostics`, `/export-trajectory` і `/config`. Він відокремлений від `commands.allowFrom` і від доступу через DM-сполучення.
|
||||
Задає явний список дозволених власників для командних/інструментальних поверхонь лише для власника. Це обліковий запис людини-оператора, який може схвалювати небезпечні дії та виконувати команди на кшталт `/diagnostics`, `/export-trajectory` і `/config`. Він окремий від `commands.allowFrom` і від доступу через спарювання DM.
|
||||
</ParamField>
|
||||
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
|
||||
Для окремого каналу: змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або збігатися з визначеним кандидатом-власником (наприклад, записом у `commands.ownerAllowFrom` або нативними метаданими власника провайдера), або мати внутрішній scope `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у канальному `allowFrom` або порожній/невизначений список кандидатів-власників **не** є достатнім — команди лише для власника в цьому каналі fail closed. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд.
|
||||
Для кожного каналу: змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або збігатися з розв’язаним кандидатом-власником (наприклад, записом у `commands.ownerAllowFrom` або нативними метаданими власника провайдера), або мати внутрішній scope `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у `allowFrom` каналу або порожній/нерозв’язаний список кандидатів-власників **не** є достатнім — команди лише для власника на цьому каналі закриті за замовчуванням. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд.
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
|
||||
Керує тим, як owner ids відображаються в системному prompt.
|
||||
Керує тим, як owner ids з’являються в системному prompt.
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplaySecret" type="string">
|
||||
За бажанням задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`.
|
||||
Необов’язково задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`.
|
||||
</ParamField>
|
||||
<ParamField path="commands.allowFrom" type="object">
|
||||
Список дозволених для кожного провайдера для авторизації команд. Коли він налаштований, це єдине джерело авторизації для команд і directives (списки дозволених каналу/сполучення та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі конкретних провайдерів його перевизначають.
|
||||
Список дозволених для авторизації команд за провайдерами. Коли налаштовано, це єдине джерело авторизації для команд і директив (списки дозволених/спарювання каналу та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі конкретних провайдерів його перевизначають.
|
||||
</ParamField>
|
||||
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
|
||||
Забезпечує застосування списків дозволених/політик для команд, коли `commands.allowFrom` не встановлено.
|
||||
Застосовує списки дозволених/політики для команд, коли `commands.allowFrom` не задано.
|
||||
</ParamField>
|
||||
|
||||
## Список команд
|
||||
|
||||
Поточне джерело істини:
|
||||
|
||||
- вбудовані core-команди походять із `src/auto-reply/commands-registry.shared.ts`
|
||||
- згенеровані команди dock походять із `src/auto-reply/commands-registry.data.ts`
|
||||
- команди plugin походять із викликів plugin `registerCommand()`
|
||||
- фактична доступність на вашому gateway усе ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugins
|
||||
- вбудовані команди ядра надходять із `src/auto-reply/commands-registry.shared.ts`
|
||||
- згенеровані команди dock надходять із `src/auto-reply/commands-registry.data.ts`
|
||||
- команди Plugin надходять із викликів Plugin `registerCommand()`
|
||||
- фактична доступність на вашому gateway все ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених Plugin
|
||||
|
||||
### Вбудовані core-команди
|
||||
### Вбудовані команди ядра
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sessions and runs">
|
||||
<Accordion title="Сесії та запуски">
|
||||
- `/new [model]` запускає нову сесію; `/reset` є псевдонімом скидання.
|
||||
- `/reset soft [message]` зберігає поточну стенограму, відкидає повторно використані ідентифікатори сесій CLI backend і повторно запускає завантаження startup/system-prompt на місці.
|
||||
- `/compact [instructions]` стискає контекст сесії. Див. [Compaction](/uk/concepts/compaction).
|
||||
- Control UI перехоплює введений `/new`, щоб створити та перемкнутися на свіжу сесію dashboard; введений `/reset` усе ще запускає скидання Gateway на місці.
|
||||
- `/reset soft [message]` зберігає поточний transcript, відкидає повторно використані ids сесій backend CLI та повторно виконує завантаження startup/system-prompt на місці.
|
||||
- `/compact [instructions]` ущільнює контекст сесії. Див. [Compaction](/uk/concepts/compaction).
|
||||
- `/stop` перериває поточний запуск.
|
||||
- `/session idle <duration|off>` і `/session max-age <duration|off>` керують закінченням терміну прив’язки гілки.
|
||||
- `/session idle <duration|off>` і `/session max-age <duration|off>` керують завершенням прив’язки треду.
|
||||
- `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`.
|
||||
- `/export-trajectory [path]` запитує схвалення exec, а потім експортує JSONL [пакет trajectory](/uk/tools/trajectory) для поточної сесії. Використовуйте це, коли потрібна хронологія prompt, tool і стенограми для однієї сесії OpenClaw. У групових чатах prompt схвалення та результат експорту надсилаються власнику приватно. Псевдонім: `/trajectory`.
|
||||
- `/export-trajectory [path]` запитує схвалення exec, а потім експортує JSONL [пакет траєкторії](/uk/tools/trajectory) для поточної сесії. Використовуйте це, коли вам потрібна хронологія prompt, tool і transcript для однієї сесії OpenClaw. У групових чатах prompt схвалення та результат експорту надсилаються власнику приватно. Псевдонім: `/trajectory`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Model and run controls">
|
||||
- `/think <level>` задає рівень мислення. Варіанти походять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а спеціальні рівні, як-от `xhigh`, `adaptive`, `max`, або бінарний `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`.
|
||||
<Accordion title="Елементи керування моделлю та запуском">
|
||||
- `/think <level>` задає рівень мислення. Варіанти надходять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а власні рівні, як-от `xhigh`, `adaptive`, `max` або двійковий `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`.
|
||||
- `/trace on|off` перемикає вивід trace plugin для поточної сесії.
|
||||
- `/fast [status|on|off]` показує або задає fast mode.
|
||||
- `/trace on|off` перемикає вивід трасування Plugin для поточної сесії.
|
||||
- `/fast [status|on|off]` показує або задає швидкий режим.
|
||||
- `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` перемикає elevated mode. Псевдонім: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` показує або задає exec defaults.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` показує або задає типові значення exec.
|
||||
- `/model [name|#|status]` показує або задає модель.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` перелічує налаштованих/доступних через auth провайдерів або моделі для провайдера; додайте `all`, щоб переглянути повний каталог цього провайдера.
|
||||
- `/queue <mode>` керує поведінкою черги (`steer`, застаріле `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) плюс параметрами на кшталт `debounce:0.5s cap:25 drop:summarize`; `/queue default` або `/queue reset` очищає перевизначення сесії. Див. [Черга команд](/uk/concepts/queue) і [Steering queue](/uk/concepts/queue-steering).
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` перелічує налаштованих/доступних через автентифікацію провайдерів або моделі для провайдера; додайте `all`, щоб переглянути повний каталог цього провайдера.
|
||||
- `/queue <mode>` керує поведінкою черги (`steer`, legacy `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) плюс опції на кшталт `debounce:0.5s cap:25 drop:summarize`; `/queue default` або `/queue reset` очищає перевизначення сесії. Див. [Черга команд](/uk/concepts/queue) і [Черга спрямування](/uk/concepts/queue-steering).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Discovery and status">
|
||||
- `/help` показує коротке зведення допомоги.
|
||||
<Accordion title="Виявлення та статус">
|
||||
- `/help` показує коротке зведення довідки.
|
||||
- `/commands` показує згенерований каталог команд.
|
||||
- `/tools [compact|verbose]` показує, що поточний agent може використовувати просто зараз.
|
||||
- `/status` показує статус виконання/runtime, включно з мітками `Execution`/`Runtime` та використанням/квотою провайдера, коли доступно.
|
||||
- `/diagnostics [note]` — це support-report flow лише для власника для багів Gateway і запусків Codex harness. Він щоразу запитує явне схвалення exec перед запуском `openclaw gateway diagnostics export --json`; не схвалюйте diagnostics правилом allow-all. Після схвалення він надсилає звіт, придатний для вставлення, з локальним шляхом до bundle, зведенням manifest, нотатками про приватність і релевантними ідентифікаторами сесій. У групових чатах prompt схвалення та звіт надсилаються власнику приватно. Коли активна сесія використовує OpenAI Codex harness, те саме схвалення також надсилає релевантний Codex feedback на сервери OpenAI, а завершена відповідь перелічує ідентифікатори сесій OpenClaw, ідентифікатори гілок Codex і команди `codex resume <thread-id>`. Див. [Експорт діагностики](/uk/gateway/diagnostics).
|
||||
- `/crestodian <request>` запускає помічник налаштування та відновлення Crestodian з DM власника.
|
||||
- `/tasks` перелічує активні/нещодавні фонові задачі для поточної сесії.
|
||||
- `/context [list|detail|json]` пояснює, як складається контекст.
|
||||
- `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз.
|
||||
- `/status` показує статус виконання/runtime, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, коли доступно.
|
||||
- `/diagnostics [note]` — це потік support-report лише для власника для помилок Gateway і запусків Codex harness. Він щоразу запитує явне схвалення exec перед запуском `openclaw gateway diagnostics export --json`; не схвалюйте діагностику правилом allow-all. Після схвалення він надсилає звіт, який можна вставити, з локальним шляхом пакета, зведенням manifest, нотатками про приватність і релевантними ids сесій. У групових чатах prompt схвалення та звіт надсилаються власнику приватно. Коли активна сесія використовує OpenAI Codex harness, те саме схвалення також надсилає релевантний feedback Codex на сервери OpenAI, а завершена відповідь перелічує ids сесій OpenClaw, ids тредів Codex і команди `codex resume <thread-id>`. Див. [Експорт діагностики](/uk/gateway/diagnostics).
|
||||
- `/crestodian <request>` запускає помічник налаштування та виправлення Crestodian з owner DM.
|
||||
- `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії.
|
||||
- `/context [list|detail|json]` пояснює, як збирається контекст.
|
||||
- `/whoami` показує ваш sender id. Псевдонім: `/id`.
|
||||
- `/usage off|tokens|full|cost` керує футером використання для кожної відповіді або друкує локальне зведення вартості.
|
||||
- `/usage off|tokens|full|cost` керує footer використання для кожної відповіді або друкує локальне зведення вартості.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skills, allowlists, approvals">
|
||||
<Accordion title="Skills, списки дозволених, схвалення">
|
||||
- `/skill <name> [input]` запускає skill за назвою.
|
||||
- `/allowlist [list|add|remove] ...` керує записами списку дозволених. Лише текст.
|
||||
- `/approve <id> <decision>` вирішує prompts схвалення exec.
|
||||
@ -174,62 +175,63 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Subagents and ACP">
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` керує запусками sub-agent для поточної сесії.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує ACP-сесіями та runtime-параметрами.
|
||||
- `/focus <target>` прив’язує поточну гілку Discord або тему/розмову Telegram до цільової сесії.
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` керує запусками під-агентів для поточного сеансу.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сеансами ACP і параметрами середовища виконання.
|
||||
- `/focus <target>` прив’язує поточну гілку Discord або тему/розмову Telegram до цілі сеансу.
|
||||
- `/unfocus` видаляє поточну прив’язку.
|
||||
- `/agents` перелічує прив’язаних до гілки agents для поточної сесії.
|
||||
- `/kill <id|#|all>` перериває одного або всіх запущених sub-agents.
|
||||
- `/steer <id|#> <message>` надсилає steering запущеному sub-agent. Псевдонім: `/tell`.
|
||||
- `/agents` показує агентів, прив’язаних до гілки, для поточного сеансу.
|
||||
- `/kill <id|#|all>` перериває один або всі запущені під-агенти.
|
||||
- `/steer <id|#> <message>` надсилає керування запущеному під-агенту. Псевдонім: `/tell`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Записи лише власником і адміністрування">
|
||||
<Accordion title="Owner-only writes and admin">
|
||||
- `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, керовану OpenClaw, у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` є псевдонімом. Записи лише для власника. Потребує `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` керує лише runtime-перевизначеннями конфігурації. Лише для власника. Потребує `commands.debug: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` — це псевдонім. Записи лише для власника. Потребує `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише для середовища виконання. Лише для власника. Потребує `commands.debug: true`.
|
||||
- `/restart` перезапускає OpenClaw, коли ввімкнено. Типово: ввімкнено; задайте `commands.restart: false`, щоб вимкнути.
|
||||
- `/send on|off|inherit` задає політику надсилання. Лише для власника.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Голос, TTS, керування каналом">
|
||||
<Accordion title="Voice, TTS, channel control">
|
||||
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` керує TTS. Див. [TTS](/uk/tools/tts).
|
||||
- `/activation mention|always` задає режим активації в групі.
|
||||
- `/bash <command>` запускає команду оболонки хоста. Лише текст. Псевдонім: `! <command>`. Потребує `commands.bash: true` плюс списки дозволів `tools.elevated`.
|
||||
- `!poll [sessionId]` перевіряє фонове завдання bash.
|
||||
- `!stop [sessionId]` зупиняє фонове завдання bash.
|
||||
- `/activation mention|always` задає режим активації групи.
|
||||
- `/bash <command>` запускає команду оболонки хоста. Лише текст. Псевдонім: `! <command>`. Потребує `commands.bash: true` і списків дозволеного `tools.elevated`.
|
||||
- `!poll [sessionId]` перевіряє фонове bash-завдання.
|
||||
- `!stop [sessionId]` зупиняє фонове bash-завдання.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Згенеровані команди dock
|
||||
### Згенеровані dock-команди
|
||||
|
||||
Команди dock перемикають маршрут відповіді поточного сеансу на інший пов’язаний
|
||||
канал. Налаштування, приклади й усунення несправностей див. у [стикуванні каналів](/uk/concepts/channel-docking).
|
||||
Dock-команди перемикають маршрут відповіді поточного сеансу на інший пов’язаний
|
||||
канал. Див. [стикування каналів](/uk/concepts/channel-docking) для налаштування,
|
||||
прикладів і усунення несправностей.
|
||||
|
||||
Команди dock генеруються з channel plugins із підтримкою нативних команд. Поточний вбудований набір:
|
||||
Dock-команди генеруються з channel plugins із підтримкою native-command. Поточний вбудований набір:
|
||||
|
||||
- `/dock-discord` (псевдонім: `/dock_discord`)
|
||||
- `/dock-mattermost` (псевдонім: `/dock_mattermost`)
|
||||
- `/dock-slack` (псевдонім: `/dock_slack`)
|
||||
- `/dock-telegram` (псевдонім: `/dock_telegram`)
|
||||
|
||||
Використовуйте команди dock із прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший пов’язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному peer каналу.
|
||||
Використовуйте dock-команди з прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший пов’язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному учаснику каналу.
|
||||
|
||||
Команди dock потребують `session.identityLinks`. Відправник-джерело й цільовий peer мають бути в одній групі ідентичностей, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправник не пов’язаний із peer Discord, команда відповідає підказкою з налаштування замість переходу до звичайного чату.
|
||||
Dock-команди потребують `session.identityLinks`. Відправник-джерело й цільовий учасник мають бути в одній групі ідентичностей, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправник не пов’язаний з учасником Discord, команда відповідає підказкою з налаштування замість передавання у звичайний чат.
|
||||
|
||||
Docking змінює лише маршрут активного сеансу. Це не створює облікові записи каналів, не надає доступ, не обходить списки дозволів каналів і не переносить історію транскрипта до іншого сеансу. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану команду dock, щоб знову перемкнути маршрут.
|
||||
Стикування змінює лише маршрут активного сеансу. Воно не створює облікові записи каналів, не надає доступ, не обходить списки дозволеного каналів і не переносить історію транскрипту в інший сеанс. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану dock-команду, щоб знову перемкнути маршрут.
|
||||
|
||||
### Команди вбудованих plugins
|
||||
### Команди вбудованих plugin
|
||||
|
||||
Вбудовані plugins можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії:
|
||||
|
||||
- `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком сполучення/налаштування пристрою. Див. [Pairing](/uk/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` тимчасово озброює високоризикові команди телефонного вузла.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` керує конфігурацією голосу Talk. У Discord нативна назва команди — `/talkvoice`.
|
||||
- `/card ...` надсилає пресети насичених карток LINE. Див. [LINE](/uk/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` перевіряє й керує вбудованим app-server harness Codex. Див. [Codex harness](/uk/plugins/codex-harness).
|
||||
- `/dreaming [on|off|status|help]` вмикає або вимикає memory dreaming. Див. [Dreaming](/uk/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком сполучення/налаштування пристрою. Див. [сполучення](/uk/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` тимчасово вмикає високоризикові команди телефонного вузла.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` керує конфігурацією голосу Talk. У Discord назва нативної команди — `/talkvoice`.
|
||||
- `/card ...` надсилає пресети LINE rich card. Див. [LINE](/uk/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` перевіряє та керує вбудованою обв’язкою сервера застосунку Codex. Див. [обв’язку Codex](/uk/plugins/codex-harness).
|
||||
- Команди лише для QQBot:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
@ -237,90 +239,90 @@ Docking змінює лише маршрут активного сеансу. Ц
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### Динамічні команди skills
|
||||
### Динамічні команди Skills
|
||||
|
||||
Skills, які може викликати користувач, також доступні як slash-команди:
|
||||
|
||||
- `/skill <name> [input]` завжди працює як загальна точка входу.
|
||||
- `/skill <name> [input]` завжди працює як універсальна точка входу.
|
||||
- skills також можуть з’являтися як прямі команди на кшталт `/prose`, коли skill/plugin їх реєструє.
|
||||
- реєстрацією нативних команд skill керують `commands.nativeSkills` і `channels.<provider>.commands.nativeSkills`.
|
||||
- реєстрація нативних skill-команд керується `commands.nativeSkills` і `channels.<provider>.commands.nativeSkills`.
|
||||
- специфікації команд можуть надавати `descriptionLocalizations` для нативних поверхонь, які підтримують локалізовані описи, зокрема Discord.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Нотатки щодо аргументів і парсера">
|
||||
- Команди приймають необов’язковий `:` між командою й аргументами (наприклад, `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` приймає псевдонім моделі, `provider/model` або назву provider (нечіткий збіг); якщо збігу немає, текст обробляється як тіло повідомлення.
|
||||
- Для повної розбивки використання provider скористайтеся `openclaw status --usage`.
|
||||
<Accordion title="Argument and parser notes">
|
||||
- Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст обробляється як тіло повідомлення.
|
||||
- Для повної розбивки використання провайдера використовуйте `openclaw status --usage`.
|
||||
- `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу.
|
||||
- У каналах із кількома обліковими записами орієнтовані на конфігурацію `/allowlist --account <id>` і `/config set channels.<provider>.accounts.<id>...` також враховують `configWrites` цільового облікового запису.
|
||||
- `/usage` керує футером використання для кожної відповіді; `/usage cost` друкує локальний підсумок вартості з журналів сеансу OpenClaw.
|
||||
- `/restart` типово ввімкнено; задайте `commands.restart: false`, щоб вимкнути.
|
||||
- У каналах із кількома обліковими записами `/allowlist --account <id>`, націлена на конфігурацію, і `/config set channels.<provider>.accounts.<id>...` також враховують `configWrites` цільового облікового запису.
|
||||
- `/usage` керує футером використання для кожної відповіді; `/usage cost` друкує локальний підсумок вартості з журналів сеансів OpenClaw.
|
||||
- `/restart` увімкнено типово; задайте `commands.restart: false`, щоб вимкнути.
|
||||
- `/plugins install <spec>` приймає ті самі специфікації plugin, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет, `git:<repo>` або `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` оновлює конфігурацію plugin і може запропонувати перезапуск.
|
||||
- `/plugins enable|disable` оновлює конфігурацію plugin і може попросити перезапуск.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Поведінка, специфічна для каналу">
|
||||
- Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступно як текст). `join` потребує guild і вибраного голосового/stage-каналу. Потребує `channels.discord.voice` і нативних команд.
|
||||
- Команди прив’язки thread у Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок thread (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`).
|
||||
- Довідник команд ACP і поведінка runtime: [агенти ACP](/uk/tools/acp-agents).
|
||||
<Accordion title="Channel-specific behavior">
|
||||
- Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текст). `join` потребує guild і вибраного голосового/stage-каналу. Потребує `channels.discord.voice` і нативних команд.
|
||||
- Команди прив’язки гілок Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок гілок (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`).
|
||||
- Довідник команд ACP і поведінка середовища виконання: [агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Безпека verbose / trace / fast / reasoning">
|
||||
- `/verbose` призначено для налагодження й додаткової видимості; тримайте його **вимкненим** під час звичайного використання.
|
||||
- `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin, і залишає звичайний докладний шум інструментів вимкненим.
|
||||
- `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в інтерфейсі Sessions, щоб очистити його й повернутися до типових значень конфігурації.
|
||||
- `/fast` залежить від provider: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема OAuth-автентифікований трафік, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic).
|
||||
<Accordion title="Verbose / trace / fast / reasoning safety">
|
||||
- `/verbose` призначено для налагодження та додаткової видимості; тримайте його **вимкненим** під час звичайного використання.
|
||||
- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать plugin, і не вмикає звичайний докладний шум інструментів.
|
||||
- `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в інтерфейсі Sessions UI, щоб очистити його й повернутися до типових значень конфігурації.
|
||||
- `/fast` залежить від провайдера: OpenAI/OpenAI Codex відображають його на `service_tier=priority` у нативних Responses endpoint, тоді як прямі публічні запити Anthropic, зокрема трафік з автентифікацією OAuth, надісланий до `api.anthropic.com`, відображають його на `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic).
|
||||
- Підсумки збоїв інструментів усе ще показуються, коли доречно, але докладний текст збою включається лише коли `/verbose` має значення `on` або `full`.
|
||||
- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin, які ви не мали наміру показувати. Бажано залишати їх вимкненими, особливо в групових чатах.
|
||||
- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішні міркування, вихід інструментів або діагностику plugin, яку ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Перемикання моделі">
|
||||
<Accordion title="Model switching">
|
||||
- `/model` негайно зберігає нову модель сеансу.
|
||||
- Якщо агент неактивний, наступний запуск одразу використовує її.
|
||||
- Якщо запуск уже активний, OpenClaw позначає live-перемикання як очікуване й перезапускається в нову модель лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або вивід відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача.
|
||||
- У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму rescue для каналів повідомлень і не надає віддалених повноважень конфігурації.
|
||||
- Якщо агент неактивний, наступний запуск одразу її використовує.
|
||||
- Якщо запуск уже активний, OpenClaw позначає live-перемикання як відкладене й перезапускається з новою моделлю лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача.
|
||||
- У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму порятунку каналу повідомлень і не надає віддалених повноважень конфігурації.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Швидкий шлях та inline-скорочення">
|
||||
- **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволів обробляються негайно (обхід черги + моделі).
|
||||
- **Обмеження згадками в групі:** повідомлення лише з командами від відправників зі списку дозволів обходять вимоги до згадок.
|
||||
- **Inline-скорочення (лише відправники зі списку дозволів):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту.
|
||||
- Приклад: `hey /status` викликає відповідь зі статусом, а решта тексту продовжує проходити звичайним потоком.
|
||||
<Accordion title="Fast path and inline shortcuts">
|
||||
- **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволеного обробляються негайно (в обхід черги + моделі).
|
||||
- **Фільтр згадок у групі:** повідомлення лише з командами від відправників зі списку дозволеного обходять вимоги до згадок.
|
||||
- **Вбудовані скорочення (лише відправники зі списку дозволеного):** певні команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту.
|
||||
- Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує звичайний потік.
|
||||
- Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- Неавторизовані повідомлення лише з командами мовчки ігноруються, а inline-токени `/...` обробляються як звичайний текст.
|
||||
- Неавторизовані повідомлення лише з командами мовчки ігноруються, а вбудовані токени `/...` обробляються як звичайний текст.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Команди Skills і нативні аргументи">
|
||||
- **Команди Skills:** skills `user-invocable` доступні як slash-команди. Імена нормалізуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`).
|
||||
- `/skill <name> [input]` запускає skill за назвою (корисно, коли обмеження нативних команд не дають створити окремі команди для кожного skill).
|
||||
- Типово команди skill пересилаються моделі як звичайний запит.
|
||||
- Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб спрямувати команду безпосередньо до інструмента (детерміновано, без моделі).
|
||||
<Accordion title="Skill commands and native arguments">
|
||||
- **Команди Skills:** Skills типу `user-invocable` доступні як slash-команди. Назви очищуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`).
|
||||
- `/skill <name> [input]` запускає skill за назвою (корисно, коли обмеження нативних команд заважають створити окремі команди для кожного skill).
|
||||
- Типово команди Skills передаються моделі як звичайний запит.
|
||||
- Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі).
|
||||
- Приклад: `/prose` (OpenProse plugin) — див. [OpenProse](/uk/prose).
|
||||
- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних опцій (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти розв’язуються відносно цільової моделі сеансу, тому специфічні для моделі опції, як-от рівні `/think`, наслідують перевизначення `/model` цього сеансу.
|
||||
- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти визначаються відносно цільової моделі сеансу, тому специфічні для моделі параметри, як-от рівні `/think`, відповідають перевизначенню `/model` цього сеансу.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` відповідає на runtime-запитання, а не на запитання конфігурації: **що цей агент може використовувати прямо зараз у цій розмові**.
|
||||
`/tools` відповідає на питання середовища виконання, а не конфігурації: **що цей агент може використовувати просто зараз у цій розмові**.
|
||||
|
||||
- Типовий `/tools` компактний і оптимізований для швидкого перегляду.
|
||||
- `/tools verbose` додає короткі описи.
|
||||
- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму `compact|verbose`.
|
||||
- Результати прив’язані до сеансу, тому зміна агента, каналу, thread, авторизації відправника або моделі може змінити вивід.
|
||||
- `/tools` включає інструменти, які фактично доступні під час runtime, зокрема core-інструменти, підключені інструменти plugin та інструменти, що належать каналу.
|
||||
- Результати обмежені сеансом, тому зміна агента, каналу, гілки, авторизації відправника або моделі може змінити вивід.
|
||||
- `/tools` включає інструменти, які фактично доступні під час виконання, зокрема основні інструменти, підключені інструменти plugin та інструменти, що належать каналу.
|
||||
|
||||
Для редагування профілю й перевизначень використовуйте панель Tools в Control UI або поверхні конфігурації/каталогу, замість того щоб трактувати `/tools` як статичний каталог.
|
||||
Для редагування профілю й перевизначень використовуйте панель Control UI Tools або поверхні конфігурації/каталогу замість того, щоб розглядати `/tools` як статичний каталог.
|
||||
|
||||
## Поверхні використання (що де показується)
|
||||
|
||||
- **Використання/квота provider** (приклад: "Claude 80% left") показується в `/status` для provider поточної моделі, коли відстеження використання ввімкнено. OpenClaw нормалізує вікна provider до `% left`; для MiniMax поля відсотків лише залишку інвертуються перед показом, а відповіді `model_remains` надають перевагу запису chat-моделі плюс позначці plan із тегом моделі.
|
||||
- **Рядки token/cache** у `/status` можуть повертатися до останнього запису використання транскрипта, коли live-знімок сеансу розріджений. Наявні ненульові live-значення все ще мають пріоритет, а fallback транскрипта також може відновити активну мітку runtime-моделі плюс більший prompt-орієнтований підсумок, коли збережені підсумки відсутні або менші.
|
||||
- **Execution проти runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично запускає сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend.
|
||||
- **Token/cost для кожної відповіді** керується `/usage off|tokens|full` (додається до звичайних відповідей).
|
||||
- `/model status` стосується **models/auth/endpoints**, а не використання.
|
||||
- **Використання/квота провайдера** (приклад: "Claude 80% left") показується в `/status` для поточного провайдера моделі, коли ввімкнено відстеження використання. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотків лише із залишком інвертуються перед відображенням, а відповіді `model_remains` віддають перевагу запису chat-моделі плюс позначці плану з тегом моделі.
|
||||
- **Рядки токенів/кешу** в `/status` можуть відступати до останнього запису використання з транскрипту, коли live-знімок сеансу розріджений. Наявні ненульові live-значення все одно мають пріоритет, а fallback на транскрипт також може відновити активну мітку моделі середовища виконання плюс більшу загальну суму, орієнтовану на prompt, коли збережені підсумки відсутні або менші.
|
||||
- **Виконання проти середовища виконання:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично запускає сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend.
|
||||
- **Токени/вартість на відповідь** керуються через `/usage off|tokens|full` (додається до звичайних відповідей).
|
||||
- `/model status` стосується **моделей/автентифікації/endpoint-ів**, а не використання.
|
||||
|
||||
## Вибір моделі (`/model`)
|
||||
|
||||
@ -337,16 +339,16 @@ Skills, які може викликати користувач, також до
|
||||
/model status
|
||||
```
|
||||
|
||||
Нотатки:
|
||||
Примітки:
|
||||
|
||||
- `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера й моделі, а також кроком Submit.
|
||||
- `/model <#>` вибирає з цього списку (і за можливості надає перевагу поточному провайдеру).
|
||||
- `/model status` показує детальний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні.
|
||||
- `/model` і `/model list` показують компактний нумерований вибір (родина моделі + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадаючими списками провайдера й моделі та кроком надсилання.
|
||||
- `/model <#>` вибирає з цього списку (і віддає перевагу поточному провайдеру, коли це можливо).
|
||||
- `/model status` показує детальний перегляд, включно з налаштованим endpoint-ом провайдера (`baseUrl`) і режимом API (`api`), коли вони доступні.
|
||||
|
||||
## Перевизначення для налагодження
|
||||
## Debug-перевизначення
|
||||
|
||||
`/debug` дає змогу встановити **лише runtime** перевизначення конфігурації (у пам’яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.debug: true`.
|
||||
`/debug` дає змогу задавати **лише runtime** перевизначення конфігурації (у пам'яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.debug: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -359,12 +361,12 @@ Skills, які може викликати користувач, також до
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення негайно застосовуються до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску.
|
||||
Перевизначення одразу застосовуються до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску.
|
||||
</Note>
|
||||
|
||||
## Вивід трасування Plugin
|
||||
## Виведення трасування Plugin
|
||||
|
||||
`/trace` дає змогу перемикати **прив’язані до сесії рядки трасування/налагодження Plugin** без увімкнення повного докладного режиму.
|
||||
`/trace` дає змогу перемикати **обмежені сеансом рядки трасування/debug Plugin** без увімкнення повного verbose-режиму.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -376,16 +378,16 @@ Skills, які може викликати користувач, також до
|
||||
|
||||
Примітки:
|
||||
|
||||
- `/trace` без аргументу показує поточний стан трасування сесії.
|
||||
- `/trace on` вмикає рядки трасування Plugin для поточної сесії.
|
||||
- `/trace` без аргументу показує поточний стан трасування сеансу.
|
||||
- `/trace on` вмикає рядки трасування Plugin для поточного сеансу.
|
||||
- `/trace off` знову вимикає їх.
|
||||
- Рядки трасування Plugin можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента.
|
||||
- Рядки трасування Plugin можуть з'являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента.
|
||||
- `/trace` не замінює `/debug`; `/debug` і далі керує лише runtime перевизначеннями конфігурації.
|
||||
- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу й далі належить до `/verbose`.
|
||||
- `/trace` не замінює `/verbose`; звичайне verbose-виведення інструментів/статусу й далі належить до `/verbose`.
|
||||
|
||||
## Оновлення конфігурації
|
||||
|
||||
`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.config: true`.
|
||||
`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.config: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -398,12 +400,12 @@ Skills, які може викликати користувач, також до
|
||||
```
|
||||
|
||||
<Note>
|
||||
Конфігурацію перевіряють перед записом; недійсні зміни відхиляються. Оновлення `/config` зберігаються після перезапусків.
|
||||
Конфігурація перевіряється перед записом; недійсні зміни відхиляються. Оновлення `/config` зберігаються між перезапусками.
|
||||
</Note>
|
||||
|
||||
## Оновлення MCP
|
||||
|
||||
`/mcp` записує визначення MCP-серверів, керовані OpenClaw, у `mcp.servers`. Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.mcp: true`.
|
||||
`/mcp` записує керовані OpenClaw визначення MCP-серверів у `mcp.servers`. Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.mcp: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -415,12 +417,12 @@ Skills, які може викликати користувач, також до
|
||||
```
|
||||
|
||||
<Note>
|
||||
`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, якими володіє Pi. Runtime-адаптери вирішують, які транспорти фактично можна виконати.
|
||||
`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. Runtime-адаптери вирішують, які транспорти фактично виконувані.
|
||||
</Note>
|
||||
|
||||
## Оновлення Plugin
|
||||
|
||||
`/plugins` дає операторам змогу переглядати виявлені Plugin і перемикати ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть за допомогою `commands.plugins: true`.
|
||||
`/plugins` дає операторам змогу переглядати виявлені plugins і перемикати ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть через `commands.plugins: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -433,43 +435,43 @@ Skills, які може викликати користувач, також до
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `/plugins list` і `/plugins show` використовують реальне виявлення Plugin у поточній робочій області разом із конфігурацією на диску.
|
||||
- `/plugins enable|disable` оновлює лише конфігурацію Plugin; це не встановлює й не видаляє Plugin.
|
||||
- Після змін увімкнення/вимкнення перезапустіть Gateway, щоб застосувати їх.
|
||||
- `/plugins list` і `/plugins show` використовують справжнє виявлення Plugin у поточному workspace плюс конфігурацію на диску.
|
||||
- `/plugins enable|disable` оновлює лише конфігурацію Plugin; це не встановлює й не видаляє plugins.
|
||||
- Після змін enable/disable перезапустіть gateway, щоб застосувати їх.
|
||||
|
||||
</Note>
|
||||
|
||||
## Примітки щодо поверхонь
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Сесії для кожної поверхні">
|
||||
- **Текстові команди** виконуються у звичайній чат-сесії (DM використовують спільну `main`, групи мають власну сесію).
|
||||
- **Нативні команди** використовують ізольовані сесії:
|
||||
<Accordion title="Сеанси на поверхню">
|
||||
- **Текстові команди** виконуються у звичайному чат-сеансі (DM спільно використовують `main`, групи мають власний сеанс).
|
||||
- **Нативні команди** використовують ізольовані сеанси:
|
||||
- Discord: `agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (спрямовує на чат-сесію через `CommandTargetSessionKey`)
|
||||
- **`/stop`** спрямовується на активну чат-сесію, щоб вона могла перервати поточний запуск.
|
||||
- Telegram: `telegram:slash:<userId>` (спрямовується на чат-сеанс через `CommandTargetSessionKey`)
|
||||
- **`/stop`** спрямовується на активний чат-сеанс, щоб він міг перервати поточний запуск.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Особливості Slack">
|
||||
`channels.slack.slashCommand` усе ще підтримується для однієї команди в стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (ті самі назви, що й у `/help`). Меню аргументів команд для Slack доставляються як ephemeral кнопки Block Kit.
|
||||
`channels.slack.slashCommand` і далі підтримується для однієї команди в стилі `/openclaw`. Якщо ввімкнути `commands.native`, потрібно створити по одній slash-команді Slack для кожної вбудованої команди (ті самі назви, що й у `/help`). Меню аргументів команд для Slack доставляються як ephemeral-кнопки Block Kit.
|
||||
|
||||
Виняток для нативних команд Slack: зареєструйте `/agentstatus` (не `/status`), бо Slack резервує `/status`. Текстова `/status` і далі працює в повідомленнях Slack.
|
||||
Виняток для нативних команд Slack: зареєструйте `/agentstatus` (а не `/status`), бо Slack резервує `/status`. Текстовий `/status` і далі працює в повідомленнях Slack.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Побічні запитання BTW
|
||||
|
||||
`/btw` — це швидке **побічне запитання** щодо поточної сесії.
|
||||
`/btw` — це швидке **побічне запитання** про поточний сеанс.
|
||||
|
||||
На відміну від звичайного чату:
|
||||
|
||||
- воно використовує поточну сесію як фоновий контекст,
|
||||
- воно виконується як окремий одноразовий виклик **без інструментів**,
|
||||
- воно не змінює майбутній контекст сесії,
|
||||
- воно не записується в історію транскрипта,
|
||||
- воно доставляється як живий побічний результат, а не як звичайне повідомлення асистента.
|
||||
- він використовує поточний сеанс як фоновий контекст,
|
||||
- він виконується як окремий одноразовий виклик **без інструментів**,
|
||||
- він не змінює майбутній контекст сеансу,
|
||||
- він не записується в історію транскрипту,
|
||||
- він доставляється як live побічний результат замість звичайного повідомлення асистента.
|
||||
|
||||
Це робить `/btw` корисним, коли потрібне тимчасове уточнення, поки основне завдання триває.
|
||||
|
||||
@ -479,10 +481,10 @@ Skills, які може викликати користувач, також до
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
Див. [Побічні запитання BTW](/uk/tools/btw), щоб ознайомитися з повною поведінкою та деталями UX клієнта.
|
||||
Див. [Побічні запитання BTW](/uk/tools/btw), щоб отримати повний опис поведінки та деталей UX клієнта.
|
||||
|
||||
## Пов’язане
|
||||
## Пов'язане
|
||||
|
||||
- [Створення skills](/uk/tools/creating-skills)
|
||||
- [Створення Skills](/uk/tools/creating-skills)
|
||||
- [Skills](/uk/tools/skills)
|
||||
- [Конфігурація Skills](/uk/tools/skills-config)
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете керувати Gateway з браузера
|
||||
- Ви хочете керувати Gateway через браузер
|
||||
- Вам потрібен доступ до Tailnet без SSH-тунелів
|
||||
sidebarTitle: Control UI
|
||||
summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T00:05:08Z"
|
||||
generated_at: "2026-05-02T09:30:24Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 982d25d48770b753faa4e57d9a284e9bff10c15cda21dd9c00848d2a6b912d41
|
||||
source_hash: b49118ee964f9efb68479494d2bc1ba4029f0ec5c12fc69bd3975c3ea5082e14
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговує Gateway:
|
||||
Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
|
||||
- типово: `http://<host>:18789/`
|
||||
- стандартно: `http://<host>:18789/`
|
||||
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
|
||||
Він працює **напряму з Gateway WebSocket** на тому самому порту.
|
||||
@ -29,124 +29,124 @@ Control UI — це невеликий односторінковий засто
|
||||
|
||||
Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`.
|
||||
|
||||
Автентифікація передається під час WebSocket handshake через:
|
||||
Автентифікація передається під час WebSocket-рукостискання через:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань dashboard зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай генерує gateway token для автентифікації зі спільним секретом під час першого підключення, але password auth також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси Gateway; паролі не зберігаються. Onboarding зазвичай генерує токен Gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Спарювання пристрою (перше підключення)
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення спарювання**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки, що запобігає несанкціонованому доступу.
|
||||
|
||||
**Що ви побачите:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Список запитів в очікуванні">
|
||||
<Step title="Перелічити запити, що очікують">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Схвалення за ID запиту">
|
||||
<Step title="Схвалити за ID запиту">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо браузер повторює спарювання зі зміненими даними автентифікації (role/scopes/public key), попередній запит в очікуванні замінюється, і створюється новий `requestId`. Перед схваленням повторно запустіть `openclaw devices list`.
|
||||
Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області дії/публічний ключ), попередній запит, що очікував, замінюється, і створюється новий `requestId`. Перед схваленням повторно запустіть `openclaw devices list`.
|
||||
|
||||
Якщо браузер уже спарено, і ви змінюєте його з доступу для читання на доступ для запису/admin, це обробляється як підвищення схвалення, а не як тихе повторне підключення. OpenClaw залишає старе схвалення активним, блокує ширше повторне підключення та просить вас явно схвалити новий набір scope.
|
||||
Якщо браузер уже сполучено, і ви змінюєте його доступ із читання на запис/адміністрування, це розглядається як підвищення схвалення, а не як непомітне повторне підключення. OpenClaw зберігає старе схвалення активним, блокує повторне підключення з ширшими правами й просить явно схвалити новий набір областей дії.
|
||||
|
||||
Після схвалення пристрій запам’ятовується і не потребуватиме повторного схвалення, якщо ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <role>`. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів.
|
||||
Після схвалення пристрій запам’ятовується й не потребуватиме повторного схвалення, якщо ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <role>`. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів.
|
||||
|
||||
<Note>
|
||||
- Прямі браузерні підключення через local loopback (`127.0.0.1` / `localhost`) схвалюються автоматично.
|
||||
- Tailscale Serve може пропустити цикл спарювання для operator sessions у Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджується, а браузер надає свою ідентичність пристрою.
|
||||
- Прямі прив’язки Tailnet, браузерні підключення з LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому перехід між браузерами або очищення даних браузера потребуватиме повторного спарювання.
|
||||
- Tailscale Serve може пропустити цикл сполучення для операторських сесій Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджена, а браузер надає ідентичність свого пристрою.
|
||||
- Прямі прив’язки Tailnet, браузерні підключення LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому перемикання браузерів або очищення даних браузера вимагатиме повторного сполучення.
|
||||
|
||||
</Note>
|
||||
|
||||
## Особиста ідентичність (локальна для браузера)
|
||||
|
||||
Control UI підтримує персональну ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається у сховищі браузера, обмежена поточним профілем браузера і не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства transcript для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або зміна браузера скидає її до порожнього стану.
|
||||
Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається у сховищі браузера, обмежена поточним профілем браузера й не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства стенограми для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або перемикання браузерів скидає її до порожнього стану.
|
||||
|
||||
Та сама локальна для браузера модель застосовується до перевизначення аватара assistant. Завантажені аватари assistant накладаються на ідентичність, визначену gateway, лише в локальному браузері та ніколи не проходять зворотний обмін через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, scripted gateways або custom dashboards).
|
||||
Та сама локальна для браузера схема застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на визначену Gateway ідентичність лише в локальному браузері й ніколи не передаються через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, скриптові шлюзи або власні дашборди).
|
||||
|
||||
## Endpoint runtime-конфігурації
|
||||
## Кінцева точка runtime-конфігурації
|
||||
|
||||
Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Цей endpoint захищений тією самою gateway auth, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а успішне отримання потребує вже дійсного gateway token/password, ідентичності Tailscale Serve або ідентичності trusted-proxy.
|
||||
Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Ця кінцева точка захищена тією самою автентифікацією Gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть її отримати, а успішне отримання потребує або вже чинного токена/пароля Gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
|
||||
## Підтримка мов
|
||||
|
||||
Control UI може локалізуватися під час першого завантаження на основі locale вашого браузера. Щоб змінити це пізніше, відкрийте **Overview -> Gateway Access -> Language**. Вибір locale міститься в картці Gateway Access, а не в Appearance.
|
||||
Control UI може локалізуватися під час першого завантаження на основі локалі вашого браузера. Щоб змінити це пізніше, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Вибір локалі розташований у картці Доступ до Gateway, а не в розділі Вигляд.
|
||||
|
||||
- Підтримувані locale: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Неанглійські переклади lazy-loaded у браузері.
|
||||
- Вибраний locale зберігається у сховищі браузера та повторно використовується під час майбутніх відвідувань.
|
||||
- Підтримувані локалі: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Переклади неанглійськими мовами ліниво завантажуються в браузері.
|
||||
- Вибрану локаль збережено в сховищі браузера й повторно використано під час майбутніх відвідувань.
|
||||
- Відсутні ключі перекладу повертаються до англійської.
|
||||
|
||||
Переклади документації генеруються для того самого набору неанглійських locale, але вбудований у сайт документації перемикач мов Mintlify обмежений кодами locale, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) все ще генерується в publish repo; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди.
|
||||
Переклади документації генеруються для того самого набору неанглійських локалей, але вбудований у сайт документації перемикач мов Mintlify обмежений кодами локалей, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) усе ще генерується в репозиторії публікації; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди.
|
||||
|
||||
## Теми вигляду
|
||||
|
||||
Панель Appearance зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [tweakcn themes](https://tweakcn.com/themes), виберіть або створіть тему, натисніть **Share** і вставте скопійоване посилання на тему в Appearance. Імпортер також приймає registry URL `https://tweakcn.com/r/themes/<id>`, URL редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/<id>`, сирі ID тем і назви типових тем, як-от `amethyst-haze`.
|
||||
Панель Вигляд зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [теми tweakcn](https://tweakcn.com/themes), виберіть або створіть тему, натисніть **Поділитися** та вставте скопійоване посилання на тему у Вигляд. Імпортер також приймає URL-адреси реєстру `https://tweakcn.com/r/themes/<id>`, URL-адреси редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/<id>`, сирі ID тем і стандартні назви тем, як-от `amethyst-haze`.
|
||||
|
||||
Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в gateway config і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; очищення перемикає активну тему назад на Claw, якщо імпортовану тему було вибрано.
|
||||
Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в конфігурацію Gateway і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; очищення перемикає активну тему назад на Claw, якщо імпортовану тему було вибрано.
|
||||
|
||||
## Що він може робити (сьогодні)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Чат і розмова">
|
||||
- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Розмовляти через browser realtime sessions. OpenAI використовує direct WebRTC, Google Live використовує constrained одноразовий browser token через WebSocket, а backend-only realtime voice plugins використовують relay transport Gateway. Relay зберігає provider credentials на Gateway, тоді як браузер stream-ить microphone PCM через RPC `talk.realtime.relay*` і надсилає tool calls `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Stream tool calls + картки live tool output у Chat (agent events).
|
||||
- Розмовляти через realtime-сесії браузера. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а realtime voice plugins, що працюють лише на бекенді, використовують ретрансляційний транспорт Gateway. Ретранслятор зберігає облікові дані провайдера на Gateway, поки браузер передає PCM з мікрофона через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Стримити виклики інструментів + живі картки виводу інструментів у Chat (події агента).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Канали, інстанси, сесії, сни">
|
||||
- Канали: вбудовані плюс стан bundled/external plugin channels, QR login і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Інстанси: список присутності + оновлення (`system-presence`).
|
||||
- Сесії: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Сни: стан dreaming, перемикач увімкнення/вимкнення та reader Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
<Accordion title="Канали, екземпляри, сесії, сни">
|
||||
- Канали: статус вбудованих і bundled/external plugin каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Екземпляри: список присутності + оновлення (`system-presence`).
|
||||
- Сесії: список + перевизначення моделі/мислення/швидкого режиму/детальності/трасування/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Сни: статус dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- Cron jobs: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: стан, увімкнення/вимкнення, встановлення, оновлення API key (`skills.*`).
|
||||
- Nodes: список + caps (`node.list`).
|
||||
- Exec approvals: редагування gateway або node allowlists + ask policy для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
<Accordion title="Cron, skills, nodes, схвалення exec">
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`).
|
||||
- Nodes: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування allowlist Gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація">
|
||||
- Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії.
|
||||
- Записи містять base-hash guard, щоб запобігти перезапису паралельних редагувань.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) виконують preflight resolution активних SecretRef для refs у надісланому config payload; unresolved active submitted refs відхиляються до запису.
|
||||
- Schema + rendering форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, matched UI hints, immediate child summaries, docs metadata на вкладених object/wildcard/array/composition nodes, а також plugin + channel schemas, коли доступні); Raw JSON editor доступний лише тоді, коли snapshot має безпечний raw round-trip.
|
||||
- Якщо snapshot не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає Form mode і вимикає Raw mode для цього snapshot.
|
||||
- У Raw JSON editor "Reset to saved" зберігає raw-authored shape (форматування, коментарі, layout `$include`) замість повторного rendering плаского snapshot, тому зовнішні редагування переживають reset, коли snapshot може безпечно виконати round-trip.
|
||||
- Структуровані значення об’єктів SecretRef відображаються read-only у текстових input форми, щоб запобігти випадковому пошкодженню object-to-string.
|
||||
- Записи містять захист base-hash, щоб запобігти перезапису паралельних змін.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для refs у надісланому payload конфігурації; нерозв’язані активні надіслані refs відхиляються перед записом.
|
||||
- Рендеринг схеми + форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, відповідними UI-підказками, підсумками безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах об’єктів/wildcard/масивів/композицій, а також схемами plugin + channel, коли доступно); редактор Raw JSON доступний лише тоді, коли знімок має безпечний raw round-trip.
|
||||
- Якщо знімок не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим Форми й вимикає режим Raw для цього знімка.
|
||||
- У редакторі Raw JSON дія "Скинути до збереженого" зберігає створену в raw форму (форматування, коментарі, розташування `$include`) замість повторного рендерингу сплощеного знімка, тому зовнішні редагування переживають скидання, коли знімок може безпечно виконати round-trip.
|
||||
- Структуровані значення об’єктів SecretRef рендеряться лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню object-to-string.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Налагодження, логи, оновлення">
|
||||
- Налагодження: snapshots status/health/models + event log + ручні RPC calls (`status`, `health`, `models.list`).
|
||||
- Логи: live tail gateway file logs із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск package/git update + перезапуск (`update.run`) зі звітом про перезапуск, потім polling `update.status` після повторного підключення для перевірки версії запущеного gateway.
|
||||
<Accordion title="Налагодження, журнали, оновлення">
|
||||
- Налагодження: знімки статусу/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнали: live tail файлових журналів Gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск package/git оновлення + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного Gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Примітки панелі Cron jobs">
|
||||
- Для ізольованих jobs delivery типово налаштовано на announce summary. Ви можете перемкнути на none, якщо потрібні internal-only runs.
|
||||
- Поля channel/target з’являються, коли вибрано announce.
|
||||
- Webhook mode використовує `delivery.mode = "webhook"` з `delivery.to`, встановленим на дійсну HTTP(S) webhook URL.
|
||||
- Для main-session jobs доступні webhook і none delivery modes.
|
||||
- Advanced edit controls містять delete-after-run, clear agent override, cron exact/stagger options, agent model/thinking overrides і best-effort delivery toggles.
|
||||
- Валідація форми inline з помилками на рівні полів; недійсні значення вимикають кнопку save, доки їх не буде виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати dedicated bearer token; якщо пропущено, webhook надсилається без auth header.
|
||||
- Deprecated fallback: збережені legacy jobs із `notify: true` все ще можуть використовувати `cron.webhook` до міграції.
|
||||
<Accordion title="Примітки до панелі завдань Cron">
|
||||
- Для ізольованих завдань доставка за замовчуванням оголошує підсумок. Можна перемкнути на none, якщо потрібні лише внутрішні запуски.
|
||||
- Поля каналу/цілі з’являються, коли вибрано announce.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, заданим як дійсна HTTP(S) webhook URL-адреса.
|
||||
- Для завдань main-session доступні режими доставки webhook і none.
|
||||
- Розширені елементи керування редагуванням містять delete-after-run, очищення перевизначення агента, точні/зміщені параметри cron, перевизначення моделі/мислення агента та перемикачі доставки best-effort.
|
||||
- Валідація форми вбудована з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його пропущено, webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий fallback: збережені legacy jobs із `notify: true` все ще можуть використовувати `cron.webhook` до міграції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -154,81 +154,82 @@ Control UI може локалізуватися під час першого з
|
||||
## Поведінка чату
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Семантика надсилання та історії">
|
||||
- `chat.send` є **неблокувальним**: він одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
|
||||
- Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають власний шлях до зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення.
|
||||
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання і `{ status: "ok" }` після завершення.
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту завеликі, Gateway може обрізати довгі текстові поля, опускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення асистента або згенеровані зображення зберігаються як керовані медіапосилання й повертаються через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи лишаються сирі base64-навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також прибирає з видимого тексту асистента службові inline-теги директив лише для відображення (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), а також витоки ASCII/повноширинних контрольних токенів моделі, і опускає записи асистента, весь видимий текст яких є лише точним silent-токеном `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату зберігає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` на короткий час повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє стан.
|
||||
- `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки в канал).
|
||||
- Пікери моделі та thinking у заголовку чату негайно змінюють активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не параметри надсилання лише для одного ходу.
|
||||
- Пікер моделі чату запитує налаштоване подання моделей Gateway. Якщо присутній `agents.defaults.models`, цей allowlist керує пікером. Інакше пікер показує явні записи `models.providers.*.models` і провайдерів із придатною автентифікацією. Повний каталог лишається доступним через debug RPC `models.list` з `view: "all"`.
|
||||
- Коли свіжі звіти Gateway про використання сесії показують високий тиск контексту, область composer чату показує сповіщення про контекст, а на рекомендованих рівнях Compaction - кнопку compact, що запускає звичайний шлях Compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання.
|
||||
<Accordion title="Семантика надсилання й історії">
|
||||
- `chat.send` є **неблокувальним**: одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь транслюється через події `chat`.
|
||||
- Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають нативний шлях до зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення.
|
||||
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення.
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту надто великі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати завеликі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення, створені асистентом, зберігаються як керовані медіапосилання й повертаються через автентифіковані медіа-URL Gateway, тож перезавантаження не залежать від того, чи залишаються необроблені base64-навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також вилучає з видимого тексту асистента лише-відображувальні вбудовані теги директив (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), а також витеклі ASCII/повноширинні керівні токени моделі, і пропускає записи асистента, увесь видимий текст яких є лише точним тихим токеном `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату залишає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` на мить повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє стан.
|
||||
- `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише в UI (без запуску агента, без доставки в канал).
|
||||
- Вибирачі моделі та режиму мислення в заголовку чату негайно патчать активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не одноразові параметри надсилання.
|
||||
- Введення `/new` у Control UI створює й перемикає на ту саму нову сесію панелі, що й Новий чат. Введення `/reset` зберігає явне скидання Gateway на місці для поточної сесії.
|
||||
- Вибирач моделі чату запитує налаштоване подання моделей Gateway. Якщо наявний `agents.defaults.models`, цей список дозволених значень керує вибирачем. Інакше вибирач показує явні записи `models.providers.*.models` плюс провайдерів із придатною автентифікацією. Повний каталог залишається доступним через налагоджувальний RPC `models.list` з `view: "all"`.
|
||||
- Коли свіжі звіти про використання сесії Gateway показують високий тиск контексту, область композитора чату показує повідомлення про контекст, а на рекомендованих рівнях Compaction - компактну кнопку, що запускає звичайний шлях Compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Режим розмови (браузерний realtime)">
|
||||
Режим розмови використовує зареєстрованого провайдера голосу realtime. Налаштуйте OpenAI за допомогою `talk.provider: "openai"` разом із `talk.providers.openai.apiKey`, або налаштуйте Google за допомогою `talk.provider: "google"` разом із `talk.providers.google.apiKey`; конфігурацію realtime-провайдера Voice Call усе ще можна повторно використати як fallback. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений auth-токен Live API для браузерної WebSocket-сесії, з інструкціями та деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, які надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані й vendor-сокети лишаються на сервері, а браузерний аудіопотік проходить через автентифіковані RPC Gateway. Prompt realtime-сесії збирає Gateway; `talk.realtime.session` не приймає надані викликачем перевизначення інструкцій.
|
||||
Режим розмови використовує зареєстрованого realtime-провайдера голосу. Налаштуйте OpenAI з `talk.provider: "openai"` плюс `talk.providers.openai.apiKey` або налаштуйте Google з `talk.provider: "google"` плюс `talk.providers.google.apiKey`; конфігурацію realtime-провайдера Voice Call усе ще можна повторно використати як резервну. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний Realtime client secret для WebRTC. Google Live отримує одноразовий обмежений токен автентифікації Live API для браузерної WebSocket-сесії, з інструкціями й деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, які надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані й vendor sockets залишаються на серверному боці, а браузерний аудіопотік проходить через автентифіковані RPC Gateway. Підказку Realtime-сесії збирає Gateway; `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем.
|
||||
|
||||
У composer чату елемент керування Talk - це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану composer показує `Connecting Talk...`, потім `Talk live`, коли аудіо підключено, або `Asking OpenClaw...`, коли realtime-виклик інструмента консультується з налаштованою більшою моделлю через `chat.send`.
|
||||
У композиторі чату елемент керування розмовою - це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли розмова запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключене, або `Asking OpenClaw...`, доки realtime-виклик інструмента звертається до налаштованої більшої моделі через `chat.send`.
|
||||
|
||||
Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє OpenAI браузерний WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup і Gateway relay browser adapter з фейковими медіа мікрофона. Команда друкує лише статус провайдера й не журналює секрети.
|
||||
Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє OpenAI browser WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup і Gateway relay browser adapter із фейковими медіа мікрофона. Команда друкує лише стан провайдера й не логує секрети.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Зупинка та переривання">
|
||||
- Натисніть **Stop** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це подальше повідомлення в поточний хід.
|
||||
- Натисніть **Зупинити** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Спрямувати** на повідомленні в черзі, щоб ввести це подальше повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним каналом.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`), щоб перервати всі активні запуски для цієї сесії.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Збереження часткового результату після переривання">
|
||||
- Коли запуск перервано, частковий текст асистента все ще може показуватися в UI.
|
||||
<Accordion title="Збереження часткових даних після переривання">
|
||||
- Коли запуск перервано, частковий текст асистента все одно може показуватися в UI.
|
||||
- Gateway зберігає перерваний частковий текст асистента в історії транскрипту, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізнити часткові результати переривання від звичайного виводу завершення.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізняти перервані часткові дані від нормального виводу завершення.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Установлення PWA та web push
|
||||
## Встановлення PWA та веб push
|
||||
|
||||
Control UI постачається з `manifest.webmanifest` і service worker, тому сучасні браузери можуть установити його як автономну PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладку або вікно браузера не відкрито.
|
||||
Control UI постачається з `manifest.webmanifest` і service worker, тож сучасні браузери можуть встановлювати його як окрему PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладка або вікно браузера не відкриті.
|
||||
|
||||
| Поверхня | Що вона робить |
|
||||
| Поверхня | Що робить |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він стає доступним. |
|
||||
| `ui/public/sw.js` | Service worker, що обробляє події `push` і кліки сповіщень. |
|
||||
| `push/vapid-keys.json` (у директорії стану OpenClaw) | Автоматично згенерована пара ключів VAPID, яку використовують для підписування Web Push-навантажень. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoint-и браузерних підписок. |
|
||||
| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують «Встановити застосунок», щойно він стає доступним. |
|
||||
| `ui/public/sw.js` | Service worker, що обробляє події `push` і кліки сповіщень. |
|
||||
| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, що використовується для підпису Web Push-навантажень. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoints браузерних підписок. |
|
||||
|
||||
Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно зафіксувати ключі (для multi-host розгортань, ротації секретів або тестів):
|
||||
Перевизначайте пару ключів VAPID через змінні середовища процесу Gateway, коли потрібно закріпити ключі (для розгортань на кількох хостах, ротації секретів або тестів):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (типово `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (за замовчуванням `mailto:openclaw@localhost`)
|
||||
|
||||
Control UI використовує ці scope-gated методи Gateway, щоб реєструвати й тестувати браузерні підписки:
|
||||
|
||||
- `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID.
|
||||
- `push.web.subscribe` — реєструє `endpoint` разом із `keys.p256dh`/`keys.auth`.
|
||||
- `push.web.unsubscribe` — видаляє зареєстрований endpoint.
|
||||
- `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`.
|
||||
- `push.web.unsubscribe` — вилучає зареєстрований endpoint.
|
||||
- `push.web.test` — надсилає тестове сповіщення до підписки викликача.
|
||||
|
||||
<Note>
|
||||
Web Push незалежний від шляху relay iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із підтримкою relay) і наявного методу `push.test`, націленого на нативне мобільне спарювання.
|
||||
Web Push не залежить від шляху iOS APNS relay (див. [Конфігурація](/uk/gateway/configuration) для relay-backed push) і наявного методу `push.test`, які націлені на нативне мобільне pairing.
|
||||
</Note>
|
||||
|
||||
## Розміщені embeds
|
||||
## Hosted embeds
|
||||
|
||||
Повідомлення асистента можуть рендерити розміщений вебвміст inline через shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`:
|
||||
Повідомлення асистента можуть рендерити hosted web content inline за допомогою shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Вимикає виконання скриптів усередині розміщених embeds.
|
||||
Вимикає виконання скриптів усередині hosted embeds.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це типовий режим, і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це стандартний режим, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для same-site документів, яким навмисно потрібні сильніші привілеї.
|
||||
@ -248,12 +249,12 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна same-origin поведінка. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором.
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна same-origin поведінка. Для більшості ігор і інтерактивних canvas, створених агентом, `scripts` є безпечнішим вибором.
|
||||
</Warning>
|
||||
|
||||
Абсолютні зовнішні URL embeds `http(s)` типово лишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Абсолютні зовнішні URL вбудовування `http(s)` за замовчуванням залишаються заблокованими. Якщо ви свідомо хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Доступ tailnet (рекомендовано)
|
||||
## Доступ через tailnet (рекомендовано)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Інтегрований Tailscale Serve (бажано)">
|
||||
@ -267,16 +268,16 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
Типово запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, і приймає їх лише тоді, коли запит потрапляє на loopback із заголовками `x-forwarded-*` від Tailscale. Для operator-сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає round trip спарювання пристрою; браузери без пристрою та з'єднання node-role усе ще проходять звичайні перевірки пристрою. Встановіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
За замовчуванням запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, та приймає їх лише коли запит надходить на loopback із заголовками Tailscale `x-forwarded-*`. Для операторських сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає повторний цикл pairing пристрою; браузери без пристрою та з'єднання з роллю node усе ще проходять звичайні перевірки пристрою. Установіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта та auth scope серіалізуються перед записами rate-limit. Тому одночасні невдалі повтори з того самого браузера можуть показати `retry later` на другому запиті замість двох звичайних невідповідностей, що змагаються паралельно.
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта й області автентифікації серіалізуються перед записами rate-limit. Тому одночасні хибні повторні спроби з того самого браузера можуть показати `retry later` на другому запиті замість двох простих невідповідностей, що виконуються паралельно.
|
||||
|
||||
<Warning>
|
||||
Auth Serve без токена припускає, що host gateway є довіреним. Якщо на цьому host може виконуватися недовірений локальний код, вимагайте token/password auth.
|
||||
Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Bind до tailnet + токен">
|
||||
<Tab title="Прив'язати до tailnet + токен">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -292,18 +293,18 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
## Небезпечний HTTP
|
||||
|
||||
Якщо ви відкриваєте dashboard через plain HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **non-secure context** і блокує WebCrypto. Типово OpenClaw **блокує** з'єднання Control UI без ідентичності пристрою.
|
||||
Якщо відкрити панель через plain HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **небезпечному контексті** й блокує WebCrypto. За замовчуванням OpenClaw **блокує** з'єднання Control UI без ідентичності пристрою.
|
||||
|
||||
Задокументовані винятки:
|
||||
Документовані винятки:
|
||||
|
||||
- сумісність insecure HTTP лише для localhost із `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішна auth operator Control UI через `gateway.auth.mode: "trusted-proxy"`
|
||||
- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- сумісність localhost-only insecure HTTP з `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішна операторська автентифікація Control UI через `gateway.auth.mode: "trusted-proxy"`
|
||||
- аварійний `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (на gateway host)
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка перемикача insecure-auth">
|
||||
@ -319,12 +320,12 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
`allowInsecureAuth` є лише локальним перемикачем сумісності:
|
||||
|
||||
- Він дозволяє localhost-сесіям Control UI продовжуватися без ідентичності пристрою в non-secure HTTP contexts.
|
||||
- Він не обходить перевірки спарювання.
|
||||
- Він не послаблює вимоги до ідентичності віддаленого (не localhost) пристрою.
|
||||
- Він дозволяє localhost-сесіям Control UI продовжувати роботу без ідентичності пристрою в небезпечних HTTP-контекстах.
|
||||
- Він не обходить перевірки pairing.
|
||||
- Він не послаблює вимоги до ідентичності пристрою для віддалених (не-localhost) з'єднань.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Лише break-glass">
|
||||
<Accordion title="Лише для аварійного доступу">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -336,42 +337,42 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI та є серйозним зниженням рівня безпеки. Швидко поверніть налаштування після екстреного використання.
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є суттєвим зниженням рівня безпеки. Швидко скасуйте це налаштування після аварійного використання.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Примітка про довірений proxy">
|
||||
- Успішна автентифікація через довірений proxy може дозволити сеанси Control UI рівня **оператор** без ідентичності пристрою.
|
||||
<Accordion title="Примітка щодо довіреного проксі">
|
||||
- Успішна автентифікація довіреного проксі може допускати сеанси Control UI з роллю **оператора** без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси Control UI з роллю вузла.
|
||||
- Зворотні proxy того самого хоста через loopback усе ще не задовольняють автентифікацію через довірений proxy; див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth).
|
||||
- Зворотні проксі same-host loopback усе одно не задовольняють автентифікацію довіреного проксі; див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Див. [Tailscale](/uk/gateway/tailscale), щоб отримати вказівки з налаштування HTTPS.
|
||||
Див. [Tailscale](/uk/gateway/tailscale) для вказівок із налаштування HTTPS.
|
||||
|
||||
## Політика безпеки вмісту
|
||||
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволено лише ресурси **того самого джерела**, URL-адреси `data:` і локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і URL-адреси зображень, відносні до протоколу, відхиляються браузером і не створюють мережевих запитів.
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **same-origin**, URL-адреси `data:` та локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не спричиняють мережевих запитів.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), усе ще відображаються, включно з автентифікованими маршрутами аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` усе ще відображаються (корисно для навантажень у межах протоколу).
|
||||
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад `/avatars/<id>`), усе ще відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує й перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` усе ще відображаються (корисно для payload у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені Control UI, усе ще відображаються.
|
||||
- Віддалені URL-адреси аватарів, що надходять із метаданих каналу, видаляються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може примусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Віддалені URL-адреси аватарів, створені метаданими каналу, видаляються допоміжними засобами аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
Вам не потрібно нічого змінювати, щоб отримати цю поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
|
||||
## Автентифікація маршруту аватара
|
||||
|
||||
Коли автентифікацію gateway налаштовано, кінцева точка аватара Control UI вимагає той самий токен gateway, що й решта API:
|
||||
Коли автентифікацію gateway налаштовано, кінцева точка аватарів Control UI вимагає той самий токен gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту медіа асистента). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення все одно відображалося на панелях.
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, тож зображення все одно відображається на dashboard.
|
||||
|
||||
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти gateway.
|
||||
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стає неавтентифікованим, відповідно до решти gateway.
|
||||
|
||||
## Збирання UI
|
||||
|
||||
@ -381,26 +382,26 @@ Gateway обслуговує статичні файли з `dist/control-ui`.
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Необов’язкова абсолютна база (коли потрібні фіксовані URL-адреси ресурсів):
|
||||
Необов’язкова абсолютна база (коли вам потрібні фіксовані URL-адреси ресурсів):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Для локальної розробки (окремий dev-сервер):
|
||||
Для локальної розробки (окремий сервер розробки):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Потім спрямуйте UI на URL Gateway WS (наприклад, `ws://127.0.0.1:18789`).
|
||||
Потім спрямуйте UI на URL-адресу WS вашого Gateway (наприклад, `ws://127.0.0.1:18789`).
|
||||
|
||||
## Налагодження/тестування: dev-сервер + віддалений Gateway
|
||||
## Налагодження/тестування: сервер розробки + віддалений Gateway
|
||||
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP-джерела. Це зручно, коли ви хочете використовувати локальний dev-сервер Vite, але Gateway працює деінде.
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати локальний сервер розробки Vite, але Gateway працює деінде.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть dev-сервер UI">
|
||||
<Step title="Запустіть сервер розробки UI">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -422,16 +423,16 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
<AccordionGroup>
|
||||
<Accordion title="Примітки">
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, закодуйте значення `gatewayUrl` для URL, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`), коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку в журналах запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як запасний варіант, і негайно видаляються після bootstrap.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) за можливості. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як fallback, і видаляються одразу після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS proxy тощо).
|
||||
- Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання Control UI не через loopback мають явно задати `gateway.controlUi.allowedOrigins` (повні джерела). Це включає віддалені dev-налаштування.
|
||||
- Під час запуску Gateway може додати локальні джерела, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, з ефективної прив’язки та порту середовища виконання, але віддалені джерела браузера все одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, крім випадків суворо контрольованого локального тестування. Це означає дозволити будь-яке джерело браузера, а не «зіставити будь-який хост, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для джерела з Host-заголовка, але це небезпечний режим безпеки.
|
||||
- Розгортання Control UI не через loopback повинні явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це стосується й віддалених середовищ розробки.
|
||||
- Запуск Gateway може заповнювати локальні origins, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, на основі ефективних runtime bind і port, але віддалені browser origins усе одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім суворо контрольованого локального тестування. Це означає дозволити будь-який browser origin, а не «зіставити з будь-яким хостом, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для origin із Host-заголовка, але це небезпечний режим безпеки.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -448,11 +449,11 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
}
|
||||
```
|
||||
|
||||
Деталі налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Панель](/uk/web/dashboard) — панель gateway
|
||||
- [Перевірки стану](/uk/gateway/health) — моніторинг стану gateway
|
||||
- [Dashboard](/uk/web/dashboard) — dashboard gateway
|
||||
- [Перевірки працездатності](/uk/gateway/health) — моніторинг працездатності gateway
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
|
||||
- [WebChat](/uk/web/webchat) — інтерфейс чату в браузері
|
||||
|
||||
Loading…
Reference in New Issue
Block a user