chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8319b9e425
commit
a2efdac3c4
@ -1,25 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви використовуєте Plugin для голосових викликів і хочете точки входу CLI
|
||||
- Вам потрібні короткі приклади для `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
|
||||
summary: Довідник CLI для `openclaw voicecall` (поверхня команд Plugin для голосових викликів)
|
||||
title: Голосовий дзвінок
|
||||
- Ви використовуєте Plugin голосових викликів і хочете отримати точки входу CLI
|
||||
- Вам потрібні швидкі приклади для `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
|
||||
summary: Довідник CLI для `openclaw voicecall` (командний інтерфейс Plugin для голосових викликів)
|
||||
title: Голосовий виклик
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T04:46:21Z"
|
||||
generated_at: "2026-05-01T05:39:40Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4090858a58b7defaff955a370c8cb0ff025ef68061e68a6c69a637de24707c0b
|
||||
source_hash: c040cf4cd984ad6d6dd302923494a7c8ee131390b803fe20a9894b077f08d5bb
|
||||
source_path: cli/voicecall.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw voicecall`
|
||||
|
||||
`voicecall` — це команда, яку надає Plugin. Вона зʼявляється лише тоді, коли Plugin голосових викликів встановлено й увімкнено.
|
||||
`voicecall` — це команда, надана Plugin. Вона з’являється лише якщо Plugin голосових викликів встановлено й увімкнено.
|
||||
|
||||
Основний документ:
|
||||
Коли Gateway запущено, операційні команди (`call`, `start`,
|
||||
`continue`, `speak`, `dtmf`, `end` і `status`) надсилаються до середовища виконання голосових викликів цього Gateway. Якщо Gateway недоступний, вони повертаються до автономного середовища виконання CLI.
|
||||
|
||||
- Plugin голосових викликів: [Voice Call](/uk/plugins/voice-call)
|
||||
Основна документація:
|
||||
|
||||
- Plugin голосових викликів: [Голосовий виклик](/uk/plugins/voice-call)
|
||||
|
||||
## Поширені команди
|
||||
|
||||
@ -34,21 +37,21 @@ openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
|
||||
openclaw voicecall end --call-id <id>
|
||||
```
|
||||
|
||||
`setup` за замовчуванням виводить зручні для читання перевірки готовності. Використовуйте `--json` для
|
||||
`setup` за замовчуванням виводить перевірки готовності в зручному для читання форматі. Використовуйте `--json` для
|
||||
скриптів:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
`status` за замовчуванням виводить активні виклики у форматі JSON. Передайте `--call-id <id>`, щоб переглянути
|
||||
`status` за замовчуванням виводить активні виклики у форматі JSON. Передайте `--call-id <id>`, щоб перевірити
|
||||
один виклик.
|
||||
|
||||
Для зовнішніх провайдерів (`twilio`, `telnyx`, `plivo`) налаштування має визначити публічну
|
||||
URL-адресу Webhook з `publicUrl`, тунелю або доступу через Tailscale. Резервний варіант обслуговування через loopback/private
|
||||
відхиляється, оскільки оператори не можуть до нього звернутися.
|
||||
Для зовнішніх провайдерів (`twilio`, `telnyx`, `plivo`) налаштування має визначити публічний
|
||||
URL Webhook з `publicUrl`, тунелю або експозиції Tailscale. Резервний варіант обслуговування через loopback/приватну мережу
|
||||
відхиляється, бо оператори не можуть до нього дістатися.
|
||||
|
||||
`smoke` виконує ті самі перевірки готовності. Він не здійснюватиме справжній телефонний виклик,
|
||||
`smoke` запускає ті самі перевірки готовності. Він не здійснюватиме реальний телефонний виклик,
|
||||
якщо не вказано одночасно `--to` і `--yes`:
|
||||
|
||||
```bash
|
||||
@ -64,7 +67,7 @@ openclaw voicecall expose --mode funnel
|
||||
openclaw voicecall expose --mode off
|
||||
```
|
||||
|
||||
Примітка щодо безпеки: відкривайте endpoint Webhook лише для мереж, яким довіряєте. За можливості віддавайте перевагу Tailscale Serve замість Funnel.
|
||||
Примітка щодо безпеки: відкривайте кінцеву точку Webhook лише для мереж, яким довіряєте. За можливості надавайте перевагу Tailscale Serve замість Funnel.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви хочете здійснити вихідний голосовий виклик з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція в телефонії
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin для голосових викликів
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з опційним голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T05:30:00Z"
|
||||
generated_at: "2026-05-01T05:39:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: ef7ab7d7499e65d4514eda607f49b10aabd5feab11cac9f808de890176606f3b
|
||||
source_hash: 08690f9f27de8a3d4d2c6056cd08edcc42f60f0592272a464c07cb1dc7fee26e
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення,
|
||||
Голосові виклики для OpenClaw через плагін. Підтримує вихідні сповіщення,
|
||||
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками списку дозволених.
|
||||
транскрипцію та вхідні виклики з політиками allowlist.
|
||||
|
||||
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює
|
||||
Плагін Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте плагін на машині, де запущено
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть Plugin">
|
||||
<Step title="Установіть плагін">
|
||||
<Tabs>
|
||||
<Tab title="З npm">
|
||||
```bash
|
||||
@ -48,28 +48,28 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої гілки пакетів; використовуйте поточну пакетовану збірку
|
||||
OpenClaw або шлях до локальної папки, доки не буде опубліковано новіший пакет npm.
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, є застарілим, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку OpenClaw
|
||||
або шлях до локальної папки, доки не буде опубліковано новіший пакет npm.
|
||||
|
||||
Після цього перезапустіть Gateway, щоб Plugin завантажився.
|
||||
Після цього перезапустіть Gateway, щоб плагін завантажився.
|
||||
|
||||
</Step>
|
||||
<Step title="Налаштуйте провайдера та Webhook">
|
||||
Установіть конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
|
||||
<Step title="Налаштуйте провайдера та webhook">
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
|
||||
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і публічно
|
||||
доступна URL-адреса Webhook.
|
||||
`provider`, облікові дані провайдера, `fromNumber` і загальнодоступна
|
||||
URL-адреса webhook.
|
||||
</Step>
|
||||
<Step title="Перевірте налаштування">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє,
|
||||
чи ввімкнено Plugin, облікові дані провайдера, доступність Webhook і те,
|
||||
що активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
`--json` для скриптів.
|
||||
Типовий вивід зручно читати в журналах чатів і терміналах. Він перевіряє
|
||||
ввімкнення плагіна, облікові дані провайдера, доступність webhook і те, що
|
||||
активний лише один аудіорежим (`streaming` або `realtime`). Для скриптів використовуйте
|
||||
`--json`.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke-тест">
|
||||
@ -78,8 +78,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
За замовчуванням обидві команди виконуються як dry run. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний виклик-сповіщення:
|
||||
Обидві команди за замовчуванням виконуються як пробні запуски. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний дзвінок зі сповіщенням:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -89,15 +89,15 @@ 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 чи простір приватної мережі, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати webhook від оператора.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але у вибраного провайдера бракує облікових даних,
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
|
||||
пропускає запуск runtime. Команди, RPC-виклики й інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
@ -164,20 +164,20 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Нотатки щодо відкриття доступу до провайдера та безпеки">
|
||||
- Twilio, Telnyx і Plivo потребують **публічно доступної** URL-адреси Webhook.
|
||||
- `mock` — локальний провайдер для розробки (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
|
||||
<Accordion title="Нотатки щодо доступності провайдера та безпеки">
|
||||
- Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси webhook.
|
||||
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
|
||||
- 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 не проходять перевірку. Продакшн: віддавайте перевагу стабільному домену або Tailscale funnel.
|
||||
- На безкоштовному рівні ngrok задайте `publicUrl` як точну URL-адресу ngrok; перевірка підпису завжди застосовується.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безкоштовного рівня Ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` відхиляється, підписи Twilio не проходять перевірку. Для production краще використовуйте стабільний домен або funnel Tailscale.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Обмеження потокових підключень">
|
||||
<Accordion title="Ліміти потокових з’єднань">
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до start.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до start на IP-адресу джерела.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів перед стартом.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети перед стартом для однієї вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувані + активні).
|
||||
|
||||
</Accordion>
|
||||
@ -185,7 +185,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Резервний runtime поки що все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — `openclaw doctor --fix`, а сумісний shim є
|
||||
шлях переписування — це `openclaw doctor --fix`, а шар сумісності є
|
||||
тимчасовим.
|
||||
|
||||
Автоматично мігровані ключі streaming:
|
||||
@ -201,40 +201,40 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає повнодуплексного голосового провайдера реального часу для live-аудіо виклику.
|
||||
Це окремо від `streaming`, який лише пересилає аудіо до
|
||||
провайдерів транскрипції в реальному часі.
|
||||
`realtime` вибирає повнодуплексного провайдера голосу в реальному часі для живого аудіо виклику.
|
||||
Він відокремлений від `streaming`, який лише пересилає аудіо
|
||||
провайдерам транскрипції в реальному часі.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
|
||||
аудіорежим на виклик.
|
||||
аудіорежим для кожного виклику.
|
||||
</Warning>
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `realtime.enabled` підтримується для Twilio Media Streams.
|
||||
- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу.
|
||||
- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми провайдерськими plugins.
|
||||
- Необроблена конфігурація, що належить провайдеру, розміщується в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням відкриває спільний realtime-інструмент `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жодного голосового провайдера реального часу не зареєстровано, Voice Call записує попередження й пропускає realtime-медіа замість того, щоб завершити весь Plugin помилкою.
|
||||
- Ключі консультативної сесії повторно використовують наявну голосову сесію, коли вона доступна, а потім переходять до номера телефону абонента/одержувача, щоб подальші консультативні виклики зберігали контекст під час виклику.
|
||||
- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
|
||||
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, міститься в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням відкриває спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного провайдера голосу в реальному часі, Voice Call записує попередження й пропускає медіа реального часу замість того, щоб зупиняти весь плагін з помилкою.
|
||||
- Ключі сесії consult повторно використовують наявну голосову сесію, коли вона доступна, а потім переходять до номера телефону абонента/одержувача, щоб подальші виклики consult зберігали контекст під час дзвінка.
|
||||
|
||||
### Політика інструментів
|
||||
|
||||
`realtime.toolPolicy` керує консультативним запуском:
|
||||
`realtime.toolPolicy` керує запуском consult:
|
||||
|
||||
| Політика | Поведінка |
|
||||
| Політика | Поведінка |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Відкриває консультативний інструмент і обмежує звичайного агента `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Відкриває консультативний інструмент і дозволяє звичайному агенту використовувати нормальну політику інструментів агента. |
|
||||
| `none` | Не відкриває консультативний інструмент. Користувацькі `realtime.tools` все одно передаються провайдеру реального часу. |
|
||||
| `safe-read-only` | Відкрити інструмент consult і обмежити звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Відкрити інструмент consult і дозволити звичайному агенту використовувати стандартну політику інструментів агента. |
|
||||
| `none` | Не відкривати інструмент consult. Власні `realtime.tools` усе одно передаються провайдеру реального часу. |
|
||||
|
||||
### Приклади провайдерів реального часу
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
Типові значення: API-ключ із `realtime.providers.google.apiKey`,
|
||||
Типові значення: ключ API з `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY` або `GOOGLE_GENERATIVE_AI_API_KEY`; модель
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025`; голос `Kore`.
|
||||
|
||||
@ -292,26 +292,26 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai) щодо специфічних для провайдера параметрів голосу
|
||||
в реальному часі.
|
||||
[провайдера OpenAI](/uk/providers/openai), щоб дізнатися про параметри голосу в реальному часі,
|
||||
специфічні для провайдера.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для live-аудіо виклику.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
|
||||
|
||||
Поточна поведінка 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 помилкою.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, міститься в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення потоку `start`, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер під’єднується, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження й пропускає потокове медіа замість того, щоб зупиняти весь плагін з помилкою.
|
||||
|
||||
### Приклади провайдерів streaming
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenAI">
|
||||
Типові значення: API-ключ `streaming.providers.openai.apiKey` або
|
||||
Типові значення: ключ API `streaming.providers.openai.apiKey` або
|
||||
`OPENAI_API_KEY`; модель `gpt-4o-transcribe`; `silenceDurationMs: 800`;
|
||||
`vadThreshold: 0.5`.
|
||||
|
||||
@ -343,7 +343,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
</Tab>
|
||||
<Tab title="xAI">
|
||||
Типові значення: API-ключ `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
|
||||
Типові значення: ключ API `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
|
||||
кінцева точка `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
|
||||
`endpointingMs: 800`; `interimResults: true`.
|
||||
|
||||
@ -378,8 +378,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
## TTS для викликів
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації Plugin з
|
||||
**такою самою структурою** — вона глибоко зливається з `messages.tts`.
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації plugin з
|
||||
**тією самою структурою** — вона глибоко об'єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -396,17 +396,17 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонний аудіопотік потребує PCM;
|
||||
поточний транспорт Microsoft не надає телефонний 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.<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, поставлені в чергу запити відтворення завершуються, а не залишають абонентів чекати на завершення відтворення.
|
||||
- Коли Twilio barge-in або завершення потоку очищає чергу TTS, запити відтворення в черзі завершуються, а не залишають абонентів у завислому стані в очікуванні завершення відтворення.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
@ -475,7 +475,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
|
||||
## Вхідні виклики
|
||||
|
||||
Типове значення політики вхідних викликів — `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
Типова вхідна політика — `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -486,20 +486,21 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller ID з низьким рівнем надійності. Plugin
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller ID із низьким рівнем достовірності. Plugin
|
||||
нормалізує надане провайдером значення `From` і порівнює його з
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставлення провайдером і
|
||||
цілісність payload, але **не** доводить володіння номером абонента
|
||||
PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller ID, а не як надійну
|
||||
ідентифікацію абонента.
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і
|
||||
цілісність корисного навантаження, але вона **не** доводить право власності
|
||||
на номер абонента PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller ID, а не як надійну
|
||||
ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують систему агента. Налаштовуйте їх за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему агента. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Контракт мовленнєвого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає до системного prompt суворий контракт мовленнєвого виводу:
|
||||
Для автовідповідей Voice Call додає строгий контракт мовленнєвого виводу до
|
||||
системного промпта:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
@ -507,41 +508,41 @@ PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller I
|
||||
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує payload, позначені як reasoning/error content.
|
||||
- Ігнорує корисні навантаження, позначені як вміст міркувань або помилок.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаданих.
|
||||
- Повертається до звичайного тексту та видаляє ймовірні вступні абзаци планування чи метаданих.
|
||||
|
||||
Це утримує мовленнєве відтворення сфокусованим на тексті для абонента й запобігає
|
||||
витоку тексту планування в аудіо.
|
||||
Це зберігає мовленнєве відтворення зосередженим на тексті для абонента та запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до поточного
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного
|
||||
стану відтворення:
|
||||
|
||||
- Очищення черги під час втручання в розмову та автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується помилкою, виклик повертається до стану `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio запускається під час підключення потоку без додаткової затримки.
|
||||
- Втручання в розмову перериває активне відтворення й очищає записи Twilio TTS, які поставлені в чергу, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка наступної відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворене.
|
||||
- Розмови realtime voice використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тож вихідні сеанси `<Connect><Stream>` залишаються підключеними.
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення не вдається, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio починається після підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення та очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тому логіка наступної відповіді може продовжитися без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Голосові розмови Realtime використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються підключеними.
|
||||
|
||||
### Пільговий період відключення потоку Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс**, перш ніж
|
||||
автоматично завершити виклик:
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед
|
||||
автоматичним завершенням виклику:
|
||||
|
||||
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не зареєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
|
||||
## Очищувач застарілих викликів
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
Webhook (наприклад, виклики в notify-режимі, які ніколи не завершуються). Типове значення —
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, що ніколи не завершуються). Типове значення —
|
||||
`0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі сповіщення.
|
||||
- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
@ -561,26 +562,26 @@ Webhook (наприклад, виклики в notify-режимі, які ні
|
||||
|
||||
## Безпека Webhook
|
||||
|
||||
Коли перед Gateway розміщено proxy або tunnel, Plugin
|
||||
реконструює публічний URL для перевірки підпису. Ці параметри
|
||||
керують тим, яким forwarded headers довіряти:
|
||||
Коли проксі або тунель розташований перед Gateway, plugin
|
||||
реконструює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
керують тим, яким перенаправленим заголовкам можна довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Список дозволених hosts із forwarding headers.
|
||||
Дозволяє hosts із заголовків forwarding за списком allowlist.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряти forwarded headers без списку дозволених.
|
||||
Довіряє перенаправленим заголовкам без allowlist.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряти forwarded headers лише тоді, коли віддалений IP запиту збігається зі списком.
|
||||
Довіряє перенаправленим заголовкам лише тоді, коли віддалена IP-адреса запиту відповідає списку.
|
||||
</ParamField>
|
||||
|
||||
Додаткові засоби захисту:
|
||||
|
||||
- **Захист від replay** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в callbacks `<Gather>`, тож застарілі/повторно відтворені speech callbacks не можуть задовольнити новіший очікуваний хід транскрипта.
|
||||
- Неавтентифіковані запити Webhook відхиляються до читання body, коли відсутні потрібні провайдеру signature headers.
|
||||
- Webhook voice-call використовує спільний pre-auth body profile (64 KB / 5 секунд) плюс per-IP in-flight cap до перевірки підпису.
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються щодо побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу у callback-ах `<Gather>`, тому застарілі або повторно відтворені callback-и мовлення не можуть задовольнити новіший очікуваний хід транскрипту.
|
||||
- Неавтентифіковані Webhook-запити відхиляються до читання тіла, якщо відсутні потрібні провайдером заголовки підпису.
|
||||
- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс обмеження одночасних запитів для кожної IP-адреси перед перевіркою підпису.
|
||||
|
||||
Приклад зі стабільним публічним host:
|
||||
|
||||
@ -616,10 +617,15 @@ openclaw voicecall latency # summarize turn latency from lo
|
||||
openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Коли Gateway уже запущено, операційні команди `voicecall` делегують виконання
|
||||
runtime voice-call, яким володіє Gateway, щоб CLI не прив'язував другий
|
||||
Webhook-сервер. Якщо Gateway недоступний, команди повертаються до
|
||||
автономного runtime CLI.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
|
||||
Використовуйте `--file <path>`, щоб указати інший log, і `--last <n>`, щоб обмежити
|
||||
Використовуйте `--file <path>`, щоб вказати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
|
||||
для затримки ходу та часу очікування прослуховування.
|
||||
для затримки ходу та часу очікування слухання.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
@ -636,9 +642,9 @@ openclaw voicecall expose --mode funnel
|
||||
|
||||
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## Gateway RPC
|
||||
## RPC Gateway
|
||||
|
||||
| Метод | Аргументи |
|
||||
| Метод | Аргументи |
|
||||
| -------------------- | ------------------------- |
|
||||
| `voicecall.initiate` | `to?`, `message`, `mode?` |
|
||||
| `voicecall.continue` | `callId`, `message` |
|
||||
@ -647,8 +653,8 @@ openclaw voicecall expose --mode funnel
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
## Пов’язане
|
||||
## Пов'язане
|
||||
|
||||
- [Talk mode](/uk/nodes/talk)
|
||||
- [Text-to-speech](/uk/tools/tts)
|
||||
- [Voice wake](/uk/nodes/voicewake)
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Перетворення тексту на мовлення](/uk/tools/tts)
|
||||
- [Голосова активація](/uk/nodes/voicewake)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user