openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-01 06:22:56 +00:00
parent 34d4c2b82f
commit e899cd767b
1 changed files with 182 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

354
docs/uk/plugins/voice-call.md
View File

@ -1,23 +1,23 @@
---
read_when:
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
- Ви налаштовуєте або розробляєте Plugin голосових викликів
- Вам потрібен голос у реальному часі або потокова транскрипція в телефонії
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії
sidebarTitle: Voice call
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
title: Plugin голосових викликів
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
title: Plugin для голосових викликів
x-i18n:
generated_at: "2026-05-01T06:08:46Z"
generated_at: "2026-05-01T06:21:24Z"
model: gpt-5.5
provider: openai
source_hash: 756e0fe4ec11d21175adabd976b8afbbc4a13caef322bbed2348a4bb928ca268
source_hash: ea655c1fab7a92056a8469018e9719e015c6492d96419dc3a6757efd90c14508
source_path: plugins/voice-call.md
workflow: 16
---
Voice calls для OpenClaw через Plugin. Підтримує вихідні сповіщення,
багатоетапні розмови, повнодуплексний голос у реальному часі, потокову
транскрипцію та вхідні виклики з політиками списку дозволених.
Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення,
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
транскрипцію та вхідні виклики з політиками allowlist.
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
@ -48,15 +48,16 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Tab>
</Tabs>
Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета
походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну упаковану збірку OpenClaw
або шлях до локальної папки, доки не буде опубліковано новіший пакет npm.
Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія
пакета походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну
пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде опубліковано
новіший npm-пакет.
Після цього перезапустіть Gateway, щоб Plugin завантажився.
</Step>
<Step title="Налаштуйте провайдера та webhook">
Установіть конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну форму див.
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
`provider`, облікові дані провайдера, `fromNumber` і публічно
доступна URL-адреса webhook.
@ -66,20 +67,20 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
openclaw voicecall setup
```
Типовий вивід зручно читати в журналах чату та терміналах. Він перевіряє
увімкнення Plugin, облікові дані провайдера, доступність webhook і те, що
активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
`--json` для скриптів.
Типовий вивід зручно читати в журналах чату та терміналах. Він перевіряє,
чи ввімкнено Plugin, облікові дані провайдера, доступність webhook
і те, що активний лише один аудіорежим (`streaming` або `realtime`).
Використовуйте `--json` для скриптів.
</Step>
<Step title="Димовий тест">
<Step title="Smoke-тест">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
Обидві команди за замовчуванням є сухими запусками. Додайте `--yes`, щоб фактично здійснити короткий
вихідний виклик зі сповіщенням:
Обидві команди за замовчуванням виконуються як пробні запуски. Додайте `--yes`,
щоб фактично здійснити короткий вихідний виклик-сповіщення:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -89,18 +90,19 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Steps>
<Warning>
Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу webhook**.
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса webhook**.
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
визначається як loopback або приватний мережевий простір, налаштування завершується помилкою замість
запуску провайдера, який не може отримувати webhook від оператора.
визначається як loopback чи простір приватної мережі, налаштування завершується
помилкою замість запуску провайдера, який не зможе отримувати webhook від оператора.
</Warning>
## Конфігурація
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
пропускає запуск середовища виконання. Команди, виклики RPC та інструменти агента все одно
повертають точну відсутню конфігурацію провайдера під час використання.
під час запуску Gateway записує попередження про неповне налаштування з
відсутніми ключами та пропускає запуск runtime. Команди, RPC-виклики й
інструменти агента все одно повертають точну відсутню конфігурацію провайдера
під час використання.
<Note>
Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
@ -164,29 +166,28 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
```
<AccordionGroup>
<Accordion title="Нотатки щодо доступності провайдера та безпеки">
<Accordion title="Нотатки щодо доступності та безпеки провайдера">
- Twilio, Telnyx і Plivo потребують **публічно доступної** URL-адреси webhook.
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
- `mock` — локальний провайдер для розробки (без мережевих викликів).
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
- `skipSignatureVerification` призначено лише для локального тестування.
- На безкоштовному рівні ngrok установіть `publicUrl` на точну URL-адресу ngrok; перевірка підпису завжди примусова.
- На безплатному рівні ngrok задайте `publicUrl` як точну URL-адресу ngrok; перевірка підпису завжди примусово ввімкнена.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
- URL-адреси безкоштовного рівня ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміститься, підписи Twilio не пройдуть перевірку. Для продакшну: віддавайте перевагу стабільному домену або Tailscale funnel.
- URL безплатного рівня Ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` розходиться, підписи Twilio не проходять перевірку. Production: надавайте перевагу стабільному домену або funnel Tailscale.
</Accordion>
<Accordion title="Обмеження потокових з’єднань">
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної IP-адреси джерела.
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних).
<Accordion title="Ліміти потокових підключень">
- `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`.
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів.
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані pre-start сокети на IP-адресу джерела.
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (pending + active).
</Accordion>
<Accordion title="Міграції застарілої конфігурації">
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
Резервний варіант середовища виконання поки що приймає старі ключі voice-call, але
шлях переписування — це `openclaw doctor --fix`, а сумісний shim є
тимчасовим.
Резервний runtime поки що приймає старі ключі voice-call, але шлях переписування —
`openclaw doctor --fix`, а сумісний shim є тимчасовим.
Автоматично мігровані ключі streaming:
@ -201,40 +202,40 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
## Голосові розмови в реальному часі
`realtime` вибирає повнодуплексного голосового провайдера реального часу для живого аудіо
виклику. Він окремий від `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`), зареєстровані їхніми Plugin провайдера.
- Сира конфігурація, що належить провайдеру, розміщується в `realtime.providers.<providerId>`.
- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жоден голосовий провайдер реального часу взагалі не зареєстрований, Voice Call записує попередження й пропускає медіа реального часу замість того, щоб завершувати весь Plugin помилкою.
- Ключі сесії консультації повторно використовують наявну голосову сесію, коли вона доступна, а потім повертаються до номера телефону абонента/одержувача, щоб подальші консультаційні виклики зберігали контекст під час виклику.
- `realtime.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу.
- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми Plugin-провайдерами.
- Raw-конфігурація, якою володіє провайдер, міститься в `realtime.providers.<providerId>`.
- Voice Call за замовчуванням надає спільний realtime-інструмент `openclaw_agent_consult`. Realtime-модель може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного голосового провайдера реального часу, Voice Call записує попередження та пропускає realtime-медіа замість того, щоб зупиняти весь Plugin з помилкою.
- Ключі 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` все одно передаються realtime-провайдеру. |
### Приклади провайдерів реального часу
### Приклади realtime-провайдерів
<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 +293,26 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Tabs>
Див. [провайдер Google](/uk/providers/google) і
[провайдер OpenAI](/uk/providers/openai) для параметрів голосу реального часу,
специфічних для провайдера.
[провайдер OpenAI](/uk/providers/openai), щоб дізнатися про параметри
голосу в реальному часі для конкретних провайдерів.
## Потокова транскрипція
`streaming` вибирає провайдера транскрипції реального часу для живого аудіо виклику.
`streaming` вибирає провайдера транскрипції в реальному часі для аудіо живого виклику.
Поточна поведінка середовища виконання:
Поточна поведінка runtime:
- `streaming.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції реального часу.
- Вбудовані провайдери транскрипції реального часу: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми Plugin провайдера.
- Сира конфігурація, що належить провайдеру, розміщується в `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`), зареєстровані їхніми Plugin-провайдерами.
- Raw-конфігурація, якою володіє провайдер, міститься в `streaming.providers.<providerId>`.
- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності realtime-транскрипції.
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження та пропускає потокове медіа замість того, щоб зупиняти весь Plugin з помилкою.
### Приклади провайдерів streaming
### Приклади 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,8 +344,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Tab>
<Tab title="xAI">
За замовчуванням: ключ API `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
кінцева точка `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
Типові значення: API-ключ `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
endpoint `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
`endpointingMs: 800`; `interimResults: true`.
```json5
@ -375,11 +376,11 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Tab>
</Tabs>
## TTS для дзвінків
## TTS для викликів
Voice Call використовує основну конфігурацію `messages.tts` для потокового
мовлення під час дзвінків. Ви можете перевизначити її в конфігурації Plugin з
**тією самою структурою** — вона глибоко об’єднується з `messages.tts`.
мовлення під час викликів. Її можна перевизначити в конфігурації plugin з
**такою самою структурою** — вона глибоко об'єднується з `messages.tts`.
```json5
{
@ -396,17 +397,17 @@ Voice Call використовує основну конфігурацію `mes
```
<Warning>
**Мовлення Microsoft ігнорується для голосових дзвінків.** Телефонному аудіо потрібен PCM;
поточний транспорт Microsoft не надає телефонний PCM-вивід.
**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM;
поточний транспорт Microsoft не надає вихід телефонного PCM.
</Warning>
Примітки щодо поведінки:
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.<provider>`.
- Core TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до голосів, вбудованих у провайдера.
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується помилкою замість змішування двох шляхів відтворення.
- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
- Коли втручання Twilio або демонтаж потоку очищує чергу очікування TTS, запити на відтворення в черзі завершуються, а не залишають абонентів, які очікують завершення відтворення, у підвішеному стані.
- Застарілі ключі `tts.<provider>` у конфігурації plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.<provider>`.
- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до власних голосів provider.
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо в такому стані телефонний TTS недоступний, запит відтворення завершується помилкою замість змішування двох шляхів відтворення.
- Коли телефонний TTS повертається до вторинного provider, Voice Call записує попередження з ланцюжком provider (`from`, `to`, `attempts`) для налагодження.
- Коли переривання Twilio або демонтаж потоку очищує чергу очікування TTS, запити відтворення в черзі завершуються, а не залишають абонентів чекати завершення відтворення.
### Приклади TTS
@ -475,7 +476,7 @@ Voice Call використовує основну конфігурацію `mes
## Вхідні виклики
Вхідна політика за замовчуванням має значення `disabled`. Щоб увімкнути вхідні виклики, задайте:
Типова вхідна політика — `disabled`. Щоб увімкнути вхідні виклики, задайте:
```json5
{
@ -486,58 +487,63 @@ Voice Call використовує основну конфігурацію `mes
```
<Warning>
`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низьким рівнем надійності. Plugin нормалізує надане провайдером значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку провайдером і цілісність корисного навантаження, але **не** доводить право власності на номер абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію ідентифікатора абонента, а не як надійну ідентичність абонента.
`inboundPolicy: "allowlist"` — це перевірка caller ID з низьким рівнем гарантії.
Plugin нормалізує надане provider значення `From` і порівнює його з
`allowFrom`. Перевірка Webhook автентифікує доставку від provider і
цілісність payload, але вона **не** доводить право власності на номер абонента
PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller ID, а не як надійну
ідентичність абонента.
</Warning>
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`,
`responseSystemPrompt` і `responseTimeoutMs`.
Автовідповіді використовують систему агентів. Налаштовуйте їх за допомогою
`responseModel`, `responseSystemPrompt` і `responseTimeoutMs`.
### Контракт озвученого виводу
### Контракт усного виводу
Для автовідповідей Voice Call додає до системного запиту суворий контракт
озвученого виводу:
Для автовідповідей Voice Call додає суворий контракт усного виводу до
системного prompt:
```text
{"spoken":"..."}
```
Voice Call обережно витягує текст для мовлення:
Voice Call захисно витягує текст мовлення:
- Ігнорує корисні навантаження, позначені як вміст міркувань/помилок.
- Розбирає прямий JSON, JSON у блоці коду або вбудовані ключі `"spoken"`.
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням/метаданими.
- Ігнорує payload, позначені як reasoning/error content.
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаданих.
Це утримує озвучене відтворення зосередженим на тексті для абонента та запобігає
Це тримає озвучене відтворення сфокусованим на тексті для абонента й запобігає
потраплянню тексту планування в аудіо.
### Поведінка запуску розмови
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до стану
живого відтворення:
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до живого
стану відтворення:
- Очищення черги під час перебивання та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
- Якщо початкове відтворення не вдається, виклик повертається до стану `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
- Початкове відтворення для потокової передачі Twilio починається під час підключення потоку без додаткової затримки.
- Перебивання перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тому логіка подальшої відповіді може продовжити роботу, не чекаючи аудіо, яке ніколи не буде відтворене.
- Голосові розмови в реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються підключеними.
- Очищення черги під час переривання та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки.
- Переривання скасовує активне відтворення й очищує записи Twilio TTS, що стоять у черзі, але ще не відтворюються. Очищені записи розв'язуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено.
- Розмови realtime voice використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сесії `<Connect><Stream>` залишаються підключеними.
### Пільговий період відключення потоку Twilio
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед
автоматичним завершенням виклику:
- Якщо потік повторно підключається протягом цього вікна, автозавершення скасовується.
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
## Прибирач застарілих викликів
## Очищувач застарілих викликів
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
становить `0` (вимкнено).
Webhook (наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення
— `0` (вимкнено).
Рекомендовані діапазони:
- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень.
- **Production:** `120`–`300` секунд для потоків у стилі notify.
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд.
```json5
@ -557,26 +563,26 @@ webhook (наприклад, виклики в режимі сповіщення
## Безпека Webhook
Коли проксі або тунель розташований перед Gateway, plugin
Коли proxy або тунель стоїть перед Gateway, plugin
відтворює публічний URL для перевірки підпису. Ці параметри
керують тим, яким пересланим заголовкам можна довіряти:
керують тим, яким forwarded-заголовкам можна довіряти:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Список дозволених хостів із заголовків переспрямування.
Allowlist хостів із forwarding-заголовків.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Довіряти пересланим заголовкам без списку дозволених хостів.
Довіряти forwarded-заголовкам без allowlist.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Довіряти пересланим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
</ParamField>
Додаткові захисти:
Додаткові засоби захисту:
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах `<Gather>`, тому застарілі або повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипта.
- Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера.
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису.
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються для побічних ефектів.
- Ходи розмов Twilio містять токен на кожен хід у callbacks `<Gather>`, тому застарілі/повторно відтворені callbacks мовлення не можуть задовольнити новіший очікуваний хід transcript.
- Неавтентифіковані Webhook-запити відхиляються до читання тіла, якщо відсутні обов'язкові заголовки підпису provider.
- Webhook voice-call використовує спільний профіль тіла pre-auth (64 КБ / 5 секунд) плюс обмеження одночасних запитів на IP до перевірки підпису.
Приклад зі стабільним публічним хостом:
@ -612,47 +618,51 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
Коли Gateway уже запущено, операційні команди `voicecall` делегують
до runtime voice-call, що належить Gateway, тому CLI не прив’язує другий
сервер Webhook. Якщо Gateway недоступний, команди повертаються до
самостійного runtime CLI.
Коли Gateway уже запущено, операційні команди `voicecall` делегуються
voice-call runtime, що належить Gateway, щоб CLI не прив'язував другий
Webhook-сервер. Якщо Gateway недоступний, команди повертаються до
автономного CLI runtime.
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call.
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
аналіз останніми N записами (за замовчуванням 200). Вивід містить p50/p90/p99
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
для затримки ходу та часу очікування прослуховування.
## Інструмент агента
Назва інструмента: `voice_call`.
| Дія | Аргументи |
| --------------- | ------------------------- |
| `initiate_call` | `message`, `to?`, `mode?` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
| Дія | Аргументи |
| --------------- | ------------------------------------------ |
| `initiate_call` | `message`, `to?`, `mode?`, `dtmfSequence?` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
Цей repo постачає відповідний документ skill за шляхом `skills/voice-call/SKILL.md`.
## Gateway RPC
| Метод | Аргументи |
| -------------------- | ------------------------- |
| `voicecall.initiate` | `to?`, `message`, `mode?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
| Метод | Аргументи |
| -------------------- | ------------------------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі notify
мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні
цифри після підключення.
## Усунення несправностей
### Налаштування не проходить перевірку доступності Webhook
### Налаштування не вдається через exposure Webhook
Запускайте налаштування з того самого середовища, у якому працює Gateway:
Запустіть налаштування з того самого середовища, у якому працює Gateway:
```bash
openclaw voicecall setup
@ -660,12 +670,12 @@ openclaw voicecall setup --json
```
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований
`publicUrl` усе одно не проходить перевірку, коли вказує на локальний або приватний мережевий
простір, тому що оператор не може виконати callback на ці адреси. Не використовуйте
`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`.
Використовуйте один шлях публічного доступу:
Використовуйте один публічний шлях exposure:
```json5
{
@ -685,32 +695,32 @@ openclaw voicecall setup --json
}
```
Після зміни конфігурації перезапустіть або перезавантажте Gateway, а потім запустіть:
Після зміни конфігурації перезапустіть або перезавантажте Gateway, потім виконайте:
```bash
openclaw voicecall setup
openclaw voicecall smoke
```
`voicecall smoke` є пробним запуском, якщо не передати `--yes`.
`voicecall smoke` — це dry run, якщо не передати `--yes`.
### Облікові дані провайдера не проходять перевірку
### Не вдається перевірити облікові дані провайдера
Перевірте вибраного провайдера та обов’язкові поля облікових даних:
- Twilio: `twilio.accountSid`, `twilio.authToken` і `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, доки він не перезапуститься або не перезавантажить
своє середовище.
### Виклики запускаються, але Webhook-и постачальника не надходять
### Виклики запускаються, але Webhook-и провайдера не надходять
Підтвердьте, що консоль постачальника вказує на точну публічну URL-адресу Webhook:
Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу Webhook:
```text
https://voice.example.com/voice/webhook
@ -726,32 +736,32 @@ openclaw voicecall tail
Поширені причини:
- `publicUrl` вказує на інший шлях, ніж `serve.path`.
- URL тунелю змінилася після запуску Gateway.
- Проксі переспрямовує запит, але видаляє або переписує заголовки host/proto.
- Брандмауер або DNS спрямовує публічне ім’я хоста не до Gateway.
- URL тунелю змінився після запуску Gateway.
- Проксі пересилає запит, але видаляє або переписує заголовки host/proto.
- Брандмауер або DNS спрямовує публічне ім’я хоста кудись іще, а не до Gateway.
- Gateway було перезапущено без увімкненого Plugin Voice Call.
Коли перед Gateway стоїть зворотний проксі або тунель, установіть
`webhookSecurity.allowedHosts` на публічне ім’я хоста або використовуйте
Коли перед Gateway стоїть зворотний проксі або тунель, задайте
`webhookSecurity.allowedHosts` як публічне ім’я хоста або використайте
`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте
`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під
вашим контролем.
### Перевірка підпису не вдається
### Не вдається перевірити підпис
Підписи постачальника перевіряються за публічною URL-адресою, яку OpenClaw відтворює
з вхідного запиту. Якщо підписи не проходять перевірку:
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює
з вхідного запиту. Якщо перевірка підписів не вдається:
- Підтвердьте, що URL Webhook постачальника точно відповідає `publicUrl`, зокрема
схемі, хосту та шляху.
- Для URL безкоштовного рівня ngrok оновлюйте `publicUrl`, коли ім’я хоста тунелю змінюється.
- Переконайтеся, що URL Webhook провайдера точно відповідає `publicUrl`, включно зі
схемою, хостом і шляхом.
- Для URL-адрес безплатного рівня ngrok оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю.
- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте
`webhookSecurity.allowedHosts`.
- Не вмикайте `skipSignatureVerification` поза локальним тестуванням.
### Не вдається приєднання Google Meet через Twilio
### Збої підключення Google Meet через Twilio
Google Meet використовує цей Plugin для приєднань через набір номера Twilio. Спочатку перевірте Voice Call:
Google Meet використовує цей Plugin для підключень через телефонний набір Twilio. Спочатку перевірте Voice Call:
```bash
openclaw voicecall setup
@ -764,26 +774,26 @@ openclaw voicecall smoke --to "+15555550123"
openclaw googlemeet setup --transport twilio
```
Якщо Voice Call працює справно, але учасник Meet так і не приєднується, перевірте номер
для набору Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
Якщо Voice Call працює, але учасник Meet так і не приєднується, перевірте номер
дозвону Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
зустріч відхиляє або ігнорує неправильну DTMF-послідовність.
Google Meet передає DTMF-послідовність Meet і вступний текст до `voicecall.start`.
Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, переспрямовує назад до
Webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ було згенеровано
після того, як телефонний учасник приєднався до зустрічі.
Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, перенаправляє назад до
Webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ було
згенеровано після приєднання телефонного учасника до зустрічі.
### У виклику в реальному часі немає мовлення
### У виклику реального часу немає мовлення
Підтвердьте, що ввімкнено лише один аудіорежим. `realtime.enabled` і
Переконайтеся, що увімкнено лише один аудіорежим. `realtime.enabled` і
`streaming.enabled` не можуть одночасно мати значення true.
Для викликів Twilio у реальному часі також перевірте:
- Plugin постачальника реального часу завантажено й зареєстровано.
- `realtime.provider` не задано або він називає зареєстрованого постачальника.
- API-ключ постачальника доступний процесу Gateway.
- `openclaw voicecall tail` показує, що медіапотік прийнято, а постачальник реального часу
- Plugin провайдера реального часу завантажено та зареєстровано.
- `realtime.provider` не задано або він називає зареєстрованого провайдера.
- Ключ API провайдера доступний процесу Gateway.
- `openclaw voicecall tail` показує, що медіапотік прийнято, а провайдер реального часу
готовий до початкового привітання.
## Пов’язане