diff --git a/docs/uk/plugins/voice-call.md b/docs/uk/plugins/voice-call.md index 22ccdaf76..e0cbf6698 100644 --- a/docs/uk/plugins/voice-call.md +++ b/docs/uk/plugins/voice-call.md @@ -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, щоб заванта - Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета - походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну упаковану збірку OpenClaw - або шлях до локальної папки, доки не буде опубліковано новіший пакет npm. + Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія + пакета походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну + пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде опубліковано + новіший npm-пакет. Після цього перезапустіть Gateway, щоб Plugin завантажився. - Установіть конфігурацію в `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` для скриптів. - + ```bash openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` - Обидві команди за замовчуванням є сухими запусками. Додайте `--yes`, щоб фактично здійснити короткий - вихідний виклик зі сповіщенням: + Обидві команди за замовчуванням виконуються як пробні запуски. Додайте `--yes`, + щоб фактично здійснити короткий вихідний виклик-сповіщення: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -89,18 +90,19 @@ Gateway, а потім перезапустіть Gateway, щоб заванта -Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу webhook**. +Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса webhook**. Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve -визначається як loopback або приватний мережевий простір, налаштування завершується помилкою замість -запуску провайдера, який не може отримувати webhook від оператора. +визначається як loopback чи простір приватної мережі, налаштування завершується +помилкою замість запуску провайдера, який не зможе отримувати webhook від оператора. ## Конфігурація Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних, -під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та -пропускає запуск середовища виконання. Команди, виклики RPC та інструменти агента все одно -повертають точну відсутню конфігурацію провайдера під час використання. +під час запуску Gateway записує попередження про неповне налаштування з +відсутніми ключами та пропускає запуск runtime. Команди, RPC-виклики й +інструменти агента все одно повертають точну відсутню конфігурацію провайдера +під час використання. Облікові дані 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, щоб заванта ``` - + - 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. - - - `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`. - - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту. - - `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної IP-адреси джерела. - - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних). + + - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`. + - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів. + - `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані pre-start сокети на IP-адресу джерела. + - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (pending + active). Старіші конфігурації, що використовують `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`, який лише пересилає аудіо +провайдерам транскрипції в реальному часі. `realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один аудіорежим для кожного виклику. -Поточна поведінка середовища виконання: +Поточна поведінка runtime: - `realtime.enabled` підтримується для Twilio Media Streams. -- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу. -- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми Plugin провайдера. -- Сира конфігурація, що належить провайдеру, розміщується в `realtime.providers.`. -- 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.`. +- 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-провайдерів - Типові значення: ключ 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, щоб заванта Див. [провайдер 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.`. -- Після того як 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.`. +- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності realtime-транскрипції. +- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження та пропускає потокове медіа замість того, щоб зупиняти весь Plugin з помилкою. -### Приклади провайдерів streaming +### Приклади streaming-провайдерів - Типові значення: ключ 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, щоб заванта - За замовчуванням: ключ 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, щоб заванта -## TTS для дзвінків +## TTS для викликів Voice Call використовує основну конфігурацію `messages.tts` для потокового -мовлення під час дзвінків. Ви можете перевизначити її в конфігурації Plugin з -**тією самою структурою** — вона глибоко об’єднується з `messages.tts`. +мовлення під час викликів. Її можна перевизначити в конфігурації plugin з +**такою самою структурою** — вона глибоко об'єднується з `messages.tts`. ```json5 { @@ -396,17 +397,17 @@ Voice Call використовує основну конфігурацію `mes ``` -**Мовлення Microsoft ігнорується для голосових дзвінків.** Телефонному аудіо потрібен PCM; -поточний транспорт Microsoft не надає телефонний PCM-вивід. +**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM; +поточний транспорт Microsoft не надає вихід телефонного PCM. Примітки щодо поведінки: -- Застарілі ключі `tts.` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.`. -- Core TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до голосів, вбудованих у провайдера. -- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується помилкою замість змішування двох шляхів відтворення. -- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження. -- Коли втручання Twilio або демонтаж потоку очищує чергу очікування TTS, запити на відтворення в черзі завершуються, а не залишають абонентів, які очікують завершення відтворення, у підвішеному стані. +- Застарілі ключі `tts.` у конфігурації plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.`. +- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до власних голосів provider. +- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML ``. Якщо в такому стані телефонний 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 ``` -`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, а не як надійну +ідентичність абонента. -Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `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 `` для цього початкового повідомлення, тому вихідні сеанси `` залишаються підключеними. +- Очищення черги під час переривання та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується. +- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби. +- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки. +- Переривання скасовує активне відтворення й очищує записи Twilio TTS, що стоять у черзі, але ще не відтворюються. Очищені записи розв'язуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено. +- Розмови realtime voice використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сесії `` залишаються підключеними. ### Пільговий період відключення потоку 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-заголовкам можна довіряти: - Список дозволених хостів із заголовків переспрямування. + Allowlist хостів із forwarding-заголовків. - Довіряти пересланим заголовкам без списку дозволених хостів. + Довіряти forwarded-заголовкам без allowlist. - Довіряти пересланим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. + Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. -Додаткові захисти: +Додаткові засоби захисту: -- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів. -- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах ``, тому застарілі або повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипта. -- Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера. -- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису. +- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються для побічних ефектів. +- Ходи розмов Twilio містять токен на кожен хід у callbacks ``, тому застарілі/повторно відтворені 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 `, щоб указати інший журнал, і `--last `, щоб обмежити -аналіз останніми 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` показує, що медіапотік прийнято, а провайдер реального часу готовий до початкового привітання. ## Пов’язане