chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d5ad58f7c9
commit
27d116a73f
File diff suppressed because it is too large
Load Diff
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок із OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin voice-call
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція в телефонії
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin голосових викликів
|
||||
- Вам потрібен голос у реальному часі або потокова транскрипція в телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційним голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосового виклику
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T05:59:37Z"
|
||||
generated_at: "2026-05-01T06:08:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: ce208e4c23e6ac6f844dce23a7e6a565b4deb1f32b8018aae7f56ea196d5245c
|
||||
source_hash: 756e0fe4ec11d21175adabd976b8afbbc4a13caef322bbed2348a4bb928ca268
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення,
|
||||
Voice calls для OpenClaw через Plugin. Підтримує вихідні сповіщення,
|
||||
багатоетапні розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками списку дозволених.
|
||||
|
||||
@ -24,22 +24,22 @@ x-i18n:
|
||||
speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Voice Call Plugin працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте Plugin на машині, де запущено
|
||||
Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<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` (повну структуру див.
|
||||
<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="Димовий тест">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Обидві команди за замовчуванням виконуються як пробні запуски. Додайте `--yes`,
|
||||
щоб фактично виконати короткий вихідний виклик-сповіщення:
|
||||
Обидві команди за замовчуванням є сухими запусками. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний виклик зі сповіщенням:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -90,21 +89,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса Webhook**.
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу webhook**.
|
||||
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
|
||||
визначається як local loopback або простір приватної мережі, налаштування завершується
|
||||
помилкою замість запуску провайдера, який не може отримувати Webhook від операторів.
|
||||
визначається як loopback або приватний мережевий простір, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не може отримувати webhook від оператора.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми
|
||||
ключами та пропускає запуск середовища виконання. Команди, RPC-виклики та інструменти
|
||||
агента все одно повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
|
||||
пропускає запуск середовища виконання. Команди, виклики RPC та інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
|
||||
<Note>
|
||||
Облікові дані голосових викликів підтримують SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` і `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.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -165,29 +164,29 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- 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` є local loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безплатного рівня ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для продакшену віддавайте перевагу стабільному домену або тунелю Tailscale.
|
||||
- На безкоштовному рівні ngrok установіть `publicUrl` на точну URL-адресу ngrok; перевірка підпису завжди примусова.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `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` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної IP-адреси джерела.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Legacy config migrations">
|
||||
<Accordion title="Міграції застарілої конфігурації">
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Резервний шлях середовища виконання поки що все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — це `openclaw doctor --fix`, а шар сумісності
|
||||
тимчасовий.
|
||||
Резервний варіант середовища виконання поки що приймає старі ключі voice-call, але
|
||||
шлях переписування — це `openclaw doctor --fix`, а сумісний shim є
|
||||
тимчасовим.
|
||||
|
||||
Автоматично мігровані ключі streaming:
|
||||
|
||||
@ -203,8 +202,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає повнодуплексного голосового провайдера реального часу для живого аудіо
|
||||
виклику. Це окремо від `streaming`, який лише пересилає аудіо до
|
||||
провайдерів транскрипції в реальному часі.
|
||||
виклику. Він окремий від `streaming`, який лише пересилає аудіо до
|
||||
провайдерів транскрипції реального часу.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
|
||||
@ -214,12 +213,12 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
Поточна поведінка середовища виконання:
|
||||
|
||||
- `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 провайдера.
|
||||
- Сира конфігурація, що належить провайдеру, розміщується в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жоден голосовий провайдер реального часу взагалі не зареєстрований, Voice Call записує попередження й пропускає медіа реального часу замість того, щоб завершувати весь Plugin помилкою.
|
||||
- Ключі сесії консультації повторно використовують наявну голосову сесію, коли вона доступна, а потім повертаються до номера телефону абонента/одержувача, щоб подальші консультаційні виклики зберігали контекст під час виклику.
|
||||
|
||||
### Політика інструментів
|
||||
|
||||
@ -227,9 +226,9 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
| Політика | Поведінка |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Відкрити інструмент консультації та обмежити звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Відкрити інструмент консультації та дозволити звичайному агенту використовувати нормальну політику інструментів агента. |
|
||||
| `none` | Не відкривати інструмент консультації. Користувацькі `realtime.tools` все одно передаються провайдеру реального часу. |
|
||||
| `safe-read-only` | Надає інструмент консультації та обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Надає інструмент консультації та дозволяє звичайному агенту використовувати звичайну політику інструментів агента. |
|
||||
| `none` | Не надає інструмент консультації. Користувацькі `realtime.tools` все одно передаються провайдеру реального часу. |
|
||||
|
||||
### Приклади провайдерів реального часу
|
||||
|
||||
@ -292,21 +291,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai), щоб переглянути параметри голосу
|
||||
реального часу, специфічні для провайдера.
|
||||
Див. [провайдер Google](/uk/providers/google) і
|
||||
[провайдер OpenAI](/uk/providers/openai) для параметрів голосу реального часу,
|
||||
специфічних для провайдера.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
|
||||
`streaming` вибирає провайдера транскрипції реального часу для живого аудіо виклику.
|
||||
|
||||
Поточна поведінка середовища виконання:
|
||||
|
||||
- `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 провайдера.
|
||||
- Сира конфігурація, що належить провайдеру, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і починає початкове привітання лише після готовності транскрипції реального часу.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жоден не зареєстрований, Voice Call записує попередження й пропускає потокове медіа замість того, щоб завершувати весь Plugin помилкою.
|
||||
|
||||
### Приклади провайдерів streaming
|
||||
|
||||
@ -344,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`.
|
||||
|
||||
@ -376,11 +375,11 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## TTS для викликів
|
||||
## TTS для дзвінків
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення у викликах. Її можна перевизначити в конфігурації Plugin з
|
||||
**такою самою формою** — вона глибоко обʼєднується з `messages.tts`.
|
||||
мовлення під час дзвінків. Ви можете перевизначити її в конфігурації Plugin з
|
||||
**тією самою структурою** — вона глибоко об’єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -397,22 +396,22 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонне аудіо потребує PCM;
|
||||
**Мовлення Microsoft ігнорується для голосових дзвінків.** Телефонному аудіо потрібен PCM;
|
||||
поточний транспорт Microsoft не надає телефонний PCM-вивід.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються за допомогою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли ввімкнено потокове медіа Twilio; інакше виклики повертаються до нативних голосів провайдера.
|
||||
- Застарілі ключі `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 barge-in або демонтаж потоку очищає чергу TTS, що очікує, запити відтворення в черзі завершуються, а не залишають абонентів у підвішеному стані в очікуванні завершення відтворення.
|
||||
- Коли втручання Twilio або демонтаж потоку очищує чергу очікування TTS, запити на відтворення в черзі завершуються, а не залишають абонентів, які очікують завершення відтворення, у підвішеному стані.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Лише основний TTS">
|
||||
<Tab title="Core TTS only">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -426,7 +425,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Перевизначення на ElevenLabs (лише виклики)">
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -450,7 +449,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке обʼєднання)">
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -487,63 +486,58 @@ 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` як фільтрацію ідентифікатора абонента, а не як надійну ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують агентну систему. Налаштовуйте за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Контракт мовленнєвого виводу
|
||||
### Контракт озвученого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає суворий контракт мовленнєвого виводу до
|
||||
системного prompt:
|
||||
Для автовідповідей Voice Call додає до системного запиту суворий контракт
|
||||
озвученого виводу:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
```
|
||||
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
Voice Call обережно витягує текст для мовлення:
|
||||
|
||||
- Ігнорує payload, позначені як вміст reasoning/error.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
|
||||
- Повертається до plain text і видаляє ймовірні вступні абзаци планування/метаданих.
|
||||
- Ігнорує корисні навантаження, позначені як вміст міркувань/помилок.
|
||||
- Розбирає прямий JSON, JSON у блоці коду або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням/метаданими.
|
||||
|
||||
Це утримує мовленнєве відтворення сфокусованим на тексті для абонента й запобігає
|
||||
Це утримує озвучене відтворення зосередженим на тексті для абонента та запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення привʼязана до поточного
|
||||
стану відтворення:
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до стану
|
||||
живого відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
|
||||
- Якщо початкове відтворення зазнає невдачі, виклик повертається до `listening`, а початкове повідомлення лишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає записи Twilio TTS у черзі, які ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжити роботу без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Розмови realtime voice використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає legacy-оновлення TwiML `<Say>` для цього початкового повідомлення, тож вихідні сеанси `<Connect><Stream>` залишаються підключеними.
|
||||
- Очищення черги під час перебивання та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
|
||||
- Якщо початкове відтворення не вдається, виклик повертається до стану `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокової передачі Twilio починається під час підключення потоку без додаткової затримки.
|
||||
- Перебивання перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тому логіка подальшої відповіді може продовжити роботу, не чекаючи аудіо, яке ніколи не буде відтворене.
|
||||
- Голосові розмови в реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються підключеними.
|
||||
|
||||
### Пільговий період відключення потоку Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед
|
||||
автоматичним завершенням виклику:
|
||||
|
||||
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не зареєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
- Якщо потік повторно підключається протягом цього вікна, автозавершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
|
||||
## Reaper застарілих викликів
|
||||
## Прибирач застарілих викликів
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
|
||||
— `0` (вимкнено).
|
||||
webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
|
||||
становить `0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
@ -564,25 +558,25 @@ Webhook (наприклад, виклики в режимі сповіщення
|
||||
## Безпека Webhook
|
||||
|
||||
Коли проксі або тунель розташований перед Gateway, plugin
|
||||
відновлює публічний URL для перевірки підпису. Ці параметри
|
||||
відтворює публічний URL для перевірки підпису. Ці параметри
|
||||
керують тим, яким пересланим заголовкам можна довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Список дозволених хостів із заголовків пересилання.
|
||||
Список дозволених хостів із заголовків переспрямування.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряти пересланим заголовкам без списку дозволених.
|
||||
Довіряти пересланим заголовкам без списку дозволених хостів.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряти пересланим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
|
||||
</ParamField>
|
||||
|
||||
Додаткові засоби захисту:
|
||||
Додаткові захисти:
|
||||
|
||||
- Захист від **повторного відтворення Webhook** увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в зворотних викликах `<Gather>`, тому застарілі або повторно відтворені мовленнєві зворотні виклики не можуть задовольнити новіший очікуваний хід транскрипта.
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах `<Gather>`, тому застарілі або повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипта.
|
||||
- Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера.
|
||||
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс обмеження одночасних запитів для кожної IP-адреси перед перевіркою підпису.
|
||||
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису.
|
||||
|
||||
Приклад зі стабільним публічним хостом:
|
||||
|
||||
@ -618,10 +612,10 @@ 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` делегують
|
||||
до runtime voice-call, що належить Gateway, тому CLI не прив’язує другий
|
||||
сервер Webhook. Якщо Gateway недоступний, команди повертаються до
|
||||
самостійного runtime CLI.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
|
||||
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
|
||||
@ -641,11 +635,11 @@ runtime voice-call, яким володіє Gateway, щоб CLI не прив’
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
Цей repo постачається з відповідним документом Skills у `skills/voice-call/SKILL.md`.
|
||||
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## RPC Gateway
|
||||
## Gateway RPC
|
||||
|
||||
| Метод | Аргументи |
|
||||
| Метод | Аргументи |
|
||||
| -------------------- | ------------------------- |
|
||||
| `voicecall.initiate` | `to?`, `message`, `mode?` |
|
||||
| `voicecall.continue` | `callId`, `message` |
|
||||
@ -656,7 +650,7 @@ runtime voice-call, яким володіє Gateway, щоб CLI не прив’
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
### Налаштування не може відкрити Webhook назовні
|
||||
### Налаштування не проходить перевірку доступності Webhook
|
||||
|
||||
Запускайте налаштування з того самого середовища, у якому працює Gateway:
|
||||
|
||||
@ -666,12 +660,12 @@ openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований
|
||||
`publicUrl` усе одно не працює, якщо він указує на локальний або приватний мережевий
|
||||
простір, оскільки оператор не може виконати зворотний виклик на ці адреси. Не використовуйте
|
||||
`publicUrl` усе одно не проходить перевірку, коли вказує на локальний або приватний мережевий
|
||||
простір, тому що оператор не може виконати callback на ці адреси. Не використовуйте
|
||||
`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`.
|
||||
|
||||
Використовуйте один публічний шлях доступу:
|
||||
Використовуйте один шлях публічного доступу:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -691,16 +685,16 @@ openclaw voicecall setup --json
|
||||
}
|
||||
```
|
||||
|
||||
Після зміни конфігурації перезапустіть або перезавантажте Gateway, а потім виконайте:
|
||||
Після зміни конфігурації перезапустіть або перезавантажте Gateway, а потім запустіть:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` — це пробний запуск, якщо не передати `--yes`.
|
||||
`voicecall smoke` є пробним запуском, якщо не передати `--yes`.
|
||||
|
||||
### Облікові дані провайдера не працюють
|
||||
### Облікові дані провайдера не проходять перевірку
|
||||
|
||||
Перевірте вибраного провайдера та обов’язкові поля облікових даних:
|
||||
|
||||
@ -710,17 +704,19 @@ openclaw voicecall smoke
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`.
|
||||
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє середовище.
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє
|
||||
середовище.
|
||||
|
||||
### Виклики запускаються, але Webhook постачальника не надходять
|
||||
### Виклики запускаються, але Webhook-и постачальника не надходять
|
||||
|
||||
Переконайтеся, що консоль постачальника вказує на точну публічну URL-адресу Webhook:
|
||||
Підтвердьте, що консоль постачальника вказує на точну публічну URL-адресу Webhook:
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
```
|
||||
|
||||
Потім перевірте стан під час виконання:
|
||||
Потім перевірте стан виконання:
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
@ -732,23 +728,30 @@ openclaw voicecall tail
|
||||
- `publicUrl` вказує на інший шлях, ніж `serve.path`.
|
||||
- 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:
|
||||
Google Meet використовує цей Plugin для приєднань через набір номера Twilio. Спочатку перевірте Voice Call:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
@ -761,20 +764,27 @@ 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 непомітно запускає Voice Call, надсилає DTMF, а потім просить Voice Call озвучити вступ після `voiceCall.postDtmfSpeechDelayMs`. Збільште цю затримку в конфігурації Plugin Google Meet, якщо перший рядок озвучується до того, як Meet допускає телефонного учасника.
|
||||
Google Meet передає DTMF-послідовність Meet і вступний текст до `voicecall.start`.
|
||||
Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, переспрямовує назад до
|
||||
Webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ було згенеровано
|
||||
після того, як телефонний учасник приєднався до зустрічі.
|
||||
|
||||
### У realtime-виклику немає мовлення
|
||||
### У виклику в реальному часі немає мовлення
|
||||
|
||||
Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно мати значення true.
|
||||
Підтвердьте, що ввімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно мати значення true.
|
||||
|
||||
Для realtime-викликів Twilio також перевірте:
|
||||
Для викликів Twilio у реальному часі також перевірте:
|
||||
|
||||
- Plugin realtime-постачальника завантажено й зареєстровано.
|
||||
- `realtime.provider` не задано або містить назву зареєстрованого постачальника.
|
||||
- Plugin постачальника реального часу завантажено й зареєстровано.
|
||||
- `realtime.provider` не задано або він називає зареєстрованого постачальника.
|
||||
- API-ключ постачальника доступний процесу Gateway.
|
||||
- `openclaw voicecall tail` показує, що медіапотік прийнято, а realtime-постачальник готовий до початкового привітання.
|
||||
- `openclaw voicecall tail` показує, що медіапотік прийнято, а постачальник реального часу
|
||||
готовий до початкового привітання.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user