diff --git a/docs/uk/plugins/voice-call.md b/docs/uk/plugins/voice-call.md index e0cbf6698..60b8fd146 100644 --- a/docs/uk/plugins/voice-call.md +++ b/docs/uk/plugins/voice-call.md @@ -2,21 +2,21 @@ read_when: - Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw - Ви налаштовуєте або розробляєте Plugin для голосових викликів - - Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії + - Вам потрібен голос у реальному часі або потокова транскрипція в телефонії sidebarTitle: Voice call -summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією -title: Plugin для голосових викликів +summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, із додатковим голосовим зв’язком у реальному часі та потоковою транскрипцією +title: Plugin голосових викликів x-i18n: - generated_at: "2026-05-01T06:21:24Z" + generated_at: "2026-05-01T06:25:14Z" model: gpt-5.5 provider: openai - source_hash: ea655c1fab7a92056a8469018e9719e015c6492d96419dc3a6757efd90c14508 + source_hash: 60ee0997676d6bb800184197b7bbb2ccde40ec30d9487c58e7b5b95b0762a6d0 source_path: plugins/voice-call.md workflow: 16 --- -Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення, -багатоходові розмови, повнодуплексний голос у реальному часі, потокову +Voice calls для OpenClaw через plugin. Підтримує вихідні сповіщення, +багатоходові розмови, повнодуплексний realtime-голос, потокову транскрипцію та вхідні виклики з політиками allowlist. **Поточні провайдери:** `twilio` (Programmable Voice + Media Streams), @@ -24,15 +24,15 @@ x-i18n: speech), `mock` (розробка/без мережі). -Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте -віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює +Voice Call plugin працює **всередині процесу Gateway**. Якщо ви використовуєте +віддалений Gateway, установіть і налаштуйте plugin на машині, де запущено Gateway, а потім перезапустіть Gateway, щоб завантажити його. ## Швидкий старт - + ```bash @@ -48,17 +48,16 @@ Gateway, а потім перезапустіть Gateway, щоб заванта - Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія - пакета походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну - пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде опубліковано - новіший npm-пакет. + Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета + походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку OpenClaw + або шлях до локальної папки, доки не буде опубліковано новіший npm-пакет. - Після цього перезапустіть Gateway, щоб Plugin завантажився. + Після цього перезапустіть Gateway, щоб plugin завантажився. - - Задайте конфігурацію в `plugins.entries.voice-call.config` (повну форму див. - у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні: + + Задайте конфігурацію в `plugins.entries.voice-call.config` (повну структуру див. + нижче в розділі [Конфігурація](#configuration)). Мінімально потрібні: `provider`, облікові дані провайдера, `fromNumber` і публічно доступна URL-адреса webhook. @@ -67,20 +66,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`, - щоб фактично здійснити короткий вихідний виклик-сповіщення: + Обидві команди за замовчуванням виконуються як dry run. Додайте `--yes`, щоб справді здійснити короткий + вихідний виклик-сповіщення: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -92,20 +91,19 @@ Gateway, а потім перезапустіть Gateway, щоб заванта Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса webhook**. Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve -визначається як loopback чи простір приватної мережі, налаштування завершується -помилкою замість запуску провайдера, який не зможе отримувати webhook від оператора. +визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість +запуску провайдера, який не зможе отримувати webhook від оператора. ## Конфігурація Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних, -під час запуску Gateway записує попередження про неповне налаштування з -відсутніми ключами та пропускає запуск runtime. Команди, 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). +Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` розв'язуються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface). ```json5 @@ -166,30 +164,31 @@ Gateway, а потім перезапустіть Gateway, щоб заванта ``` - - - Twilio, Telnyx і Plivo потребують **публічно доступної** URL-адреси webhook. + + - Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси webhook. - `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 не проходять перевірку. Production: надавайте перевагу стабільному домену або funnel Tailscale. + - URL-адреси безплатного тарифу Ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Продакшн: надавайте перевагу стабільному домену або funnel Tailscale. - - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`. + - `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`. - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів. - `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані pre-start сокети на IP-адресу джерела. - - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (pending + active). + - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів media stream (pending + active). Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`. - Резервний runtime поки що приймає старі ключі voice-call, але шлях переписування — - `openclaw doctor --fix`, а сумісний shim є тимчасовим. + Runtime fallback наразі все ще приймає старі ключі voice-call, але + шлях переписування — `openclaw doctor --fix`, а compat shim є + тимчасовим. - Автоматично мігровані ключі streaming: + Автоматично мігровані streaming-ключі: - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -200,11 +199,11 @@ Gateway, а потім перезапустіть Gateway, щоб заванта -## Голосові розмови в реальному часі +## Realtime-голосові розмови -`realtime` вибирає повнодуплексного голосового провайдера в реальному часі для -аудіо живого виклику. Це окремо від `streaming`, який лише пересилає аудіо -провайдерам транскрипції в реальному часі. +`realtime` вибирає повнодуплексного realtime-голосового провайдера для live-аудіо +виклику. Це окремо від `streaming`, який лише пересилає аудіо до +провайдерів realtime-транскрипції. `realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один @@ -214,12 +213,12 @@ Gateway, а потім перезапустіть Gateway, щоб заванта Поточна поведінка runtime: - `realtime.enabled` підтримується для Twilio Media Streams. -- `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.provider` необов'язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого realtime-голосового провайдера. +- Вбудовані realtime-голосові провайдери: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми провайдерськими plugins. +- Необроблена конфігурація, якою володіє провайдер, зберігається в `realtime.providers.`. +- Voice Call за замовчуванням відкриває спільний realtime-інструмент `openclaw_agent_consult`. Realtime-модель може викликати його, коли абонент просить глибшого міркування, поточної інформації або звичайних інструментів OpenClaw. +- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жоден realtime-голосовий провайдер узагалі не зареєстрований, Voice Call записує попередження й пропускає realtime media замість того, щоб зупиняти весь plugin. +- Ключі consult-сеансу повторно використовують наявний голосовий сеанс, коли він доступний, а потім відступають до номера телефону абонента/отримувача, щоб наступні consult-виклики зберігали контекст під час виклику. ### Політика інструментів @@ -227,15 +226,15 @@ Gateway, а потім перезапустіть Gateway, щоб заванта | Політика | Поведінка | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `safe-read-only` | Надає consult-інструмент і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. | -| `owner` | Надає consult-інструмент і дозволяє звичайному агенту використовувати звичайну політику інструментів агента. | -| `none` | Не надає consult-інструмент. Користувацькі `realtime.tools` все одно передаються realtime-провайдеру. | +| `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,27 +291,26 @@ Gateway, а потім перезапустіть Gateway, щоб заванта -Див. [провайдер Google](/uk/providers/google) і -[провайдер OpenAI](/uk/providers/openai), щоб дізнатися про параметри -голосу в реальному часі для конкретних провайдерів. +Див. [провайдера Google](/uk/providers/google) і +[провайдера OpenAI](/uk/providers/openai), щоб переглянути специфічні для провайдера параметри realtime-голосу. ## Потокова транскрипція -`streaming` вибирає провайдера транскрипції в реальному часі для аудіо живого виклику. +`streaming` вибирає провайдера realtime-транскрипції для live-аудіо виклику. Поточна поведінка runtime: -- `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.provider` необов'язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера realtime-транскрипції. +- Вбудовані провайдери realtime-транскрипції: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми провайдерськими plugins. +- Необроблена конфігурація, якою володіє провайдер, зберігається в `streaming.providers.`. +- Після того як Twilio надсилає прийняте stream-повідомлення `start`, Voice Call негайно реєструє stream, ставить вхідні media в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності realtime-транскрипції. +- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жоден не зареєстрований, Voice Call записує попередження й пропускає media streaming замість того, щоб зупиняти весь plugin. ### Приклади streaming-провайдерів - Типові значення: API-ключ `streaming.providers.openai.apiKey` або + Значення за замовчуванням: API-ключ `streaming.providers.openai.apiKey` або `OPENAI_API_KEY`; модель `gpt-4o-transcribe`; `silenceDurationMs: 800`; `vadThreshold: 0.5`. @@ -379,8 +377,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта ## TTS для викликів Voice Call використовує основну конфігурацію `messages.tts` для потокового -мовлення під час викликів. Її можна перевизначити в конфігурації plugin з -**такою самою структурою** — вона глибоко об'єднується з `messages.tts`. +мовлення під час викликів. Її можна перевизначити в конфігурації Plugin з +**тією самою структурою** — вона глибоко об'єднується з `messages.tts`. ```json5 { @@ -397,17 +395,17 @@ Voice Call використовує основну конфігурацію `mes ``` -**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM; -поточний транспорт Microsoft не надає вихід телефонного PCM. +**Мовлення Microsoft ігнорується для голосових викликів.** Телефонний аудіопотік потребує PCM; +поточний транспорт Microsoft не надає телефонний PCM-вивід. Примітки щодо поведінки: -- Застарілі ключі `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.` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.`. +- Core TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до нативних голосів провайдера. +- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS у цьому стані недоступний, запит відтворення завершується помилкою замість змішування двох шляхів відтворення. +- Коли телефонний TTS повертається до резервного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження. +- Коли barge-in Twilio або розбирання потоку очищає чергу очікування TTS, поставлені в чергу запити відтворення завершуються, а не залишають абонентів чекати на завершення відтворення. ### Приклади TTS @@ -476,7 +474,7 @@ Voice Call використовує основну конфігурацію `mes ## Вхідні виклики -Типова вхідна політика — `disabled`. Щоб увімкнути вхідні виклики, задайте: +Вхідна політика типово має значення `disabled`. Щоб увімкнути вхідні виклики, задайте: ```json5 { @@ -487,21 +485,15 @@ Voice Call використовує основну конфігурацію `mes ``` -`inboundPolicy: "allowlist"` — це перевірка caller ID з низьким рівнем гарантії. -Plugin нормалізує надане provider значення `From` і порівнює його з -`allowFrom`. Перевірка Webhook автентифікує доставку від provider і -цілісність payload, але вона **не** доводить право власності на номер абонента -PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller ID, а не як надійну -ідентичність абонента. +`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низьким рівнем гарантій. Plugin нормалізує надане провайдером значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку провайдером і цілісність payload, але вона **не** доводить право власності на номер абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію за ідентифікатором абонента, а не як надійну ідентичність абонента. -Автовідповіді використовують систему агентів. Налаштовуйте їх за допомогою -`responseModel`, `responseSystemPrompt` і `responseTimeoutMs`. +Автовідповіді використовують систему агента. Налаштуйте їх за допомогою `responseModel`, +`responseSystemPrompt` і `responseTimeoutMs`. -### Контракт усного виводу +### Контракт голосового виводу -Для автовідповідей Voice Call додає суворий контракт усного виводу до -системного prompt: +Для автовідповідей Voice Call додає до системного prompt строгий контракт голосового виводу: ```text {"spoken":"..."} @@ -509,42 +501,42 @@ PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller I Voice Call захисно витягує текст мовлення: -- Ігнорує payload, позначені як reasoning/error content. +- Ігнорує payload, позначені як вміст reasoning/error. - Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`. -- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаданих. +- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/meta. -Це тримає озвучене відтворення сфокусованим на тексті для абонента й запобігає +Це утримує голосове відтворення зосередженим на тексті для абонента й запобігає потраплянню тексту планування в аудіо. ### Поведінка запуску розмови -Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до живого +Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного стану відтворення: -- Очищення черги під час переривання та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується. +- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно відтворюється. - Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби. -- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки. -- Переривання скасовує активне відтворення й очищує записи Twilio TTS, що стоять у черзі, але ще не відтворюються. Очищені записи розв'язуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено. -- Розмови realtime voice використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сесії `` залишаються підключеними. +- Початкове відтворення для потокового передавання Twilio починається під час підключення потоку без додаткової затримки. +- Barge-in перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тому логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не відтвориться. +- Голосові розмови в реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сесії `` залишаються приєднаними. ### Пільговий період відключення потоку Twilio -Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед +Коли медіапотік Twilio відключається, Voice Call очікує **2000 мс** перед автоматичним завершенням виклику: - Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується. - Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам. -## Очищувач застарілих викликів +## Очищення застарілих викликів Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний -Webhook (наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення +Webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення — `0` (вимкнено). Рекомендовані діапазони: -- **Production:** `120`–`300` секунд для потоків у стилі notify. -- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд. +- **Production:** `120`–`300` секунд для сценаріїв у стилі сповіщень. +- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд. ```json5 { @@ -563,26 +555,26 @@ Webhook (наприклад, виклики в режимі notify, які ні ## Безпека Webhook -Коли proxy або тунель стоїть перед Gateway, plugin -відтворює публічний URL для перевірки підпису. Ці параметри -керують тим, яким forwarded-заголовкам можна довіряти: +Коли перед Gateway розміщено проксі або тунель, Plugin відтворює +публічну URL-адресу для перевірки підпису. Ці параметри керують тим, +яким forwarded headers довіряти: - Allowlist хостів із forwarding-заголовків. + Список дозволених хостів із forwarding headers. - Довіряти forwarded-заголовкам без allowlist. + Довіряти forwarded headers без allowlist. - Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. + Довіряти forwarded headers лише тоді, коли віддалена IP-адреса запиту відповідає списку. Додаткові засоби захисту: -- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються для побічних ефектів. -- Ходи розмов Twilio містять токен на кожен хід у callbacks ``, тому застарілі/повторно відтворені callbacks мовлення не можуть задовольнити новіший очікуваний хід transcript. -- Неавтентифіковані Webhook-запити відхиляються до читання тіла, якщо відсутні обов'язкові заголовки підпису provider. -- Webhook voice-call використовує спільний профіль тіла pre-auth (64 КБ / 5 секунд) плюс обмеження одночасних запитів на IP до перевірки підпису. +- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються щодо побічних ефектів. +- Ходи розмови Twilio містять токен на кожен хід у callbacks ``, тому застарілі/повторно відтворені callbacks мовлення не можуть задовольнити новіший очікуваний хід transcript. +- Неавтентифіковані запити Webhook відхиляються до читання тіла, коли відсутні обов'язкові заголовки підпису провайдера. +- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс обмеження in-flight на IP перед перевіркою підпису. Приклад зі стабільним публічним хостом: @@ -618,15 +610,15 @@ openclaw voicecall latency # summarize turn latency from lo openclaw voicecall expose --mode funnel ``` -Коли Gateway уже запущено, операційні команди `voicecall` делегуються -voice-call runtime, що належить Gateway, щоб CLI не прив'язував другий -Webhook-сервер. Якщо Gateway недоступний, команди повертаються до -автономного CLI runtime. +Коли Gateway уже запущено, операційні команди `voicecall` делегують +runtime voice-call, яким володіє Gateway, щоб CLI не прив'язував другий +сервер Webhook. Якщо Gateway недоступний, команди повертаються до +окремого runtime CLI. -`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call. +`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call. Використовуйте `--file `, щоб указати інший журнал, і `--last `, щоб обмежити аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99 -для затримки ходу та часу очікування прослуховування. +для затримки ходу й часу очікування прослуховування. ## Інструмент агента @@ -641,7 +633,7 @@ Webhook-сервер. Якщо Gateway недоступний, команди п | `end_call` | `callId` | | `get_status` | `callId` | -Цей repo постачає відповідний документ skill за шляхом `skills/voice-call/SKILL.md`. +Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`. ## Gateway RPC @@ -654,13 +646,13 @@ Webhook-сервер. Якщо Gateway недоступний, команди п | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі notify +`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі сповіщення мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні цифри після підключення. ## Усунення несправностей -### Налаштування не вдається через exposure Webhook +### Налаштування не може відкрити Webhook назовні Запустіть налаштування з того самого середовища, у якому працює Gateway: @@ -670,12 +662,12 @@ openclaw voicecall setup --json ``` Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований -`publicUrl` усе одно завершується помилкою, коли він вказує на локальний або приватний мережевий -простір, тому що оператор не може викликати ці адреси у відповідь. Не використовуйте +`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 { @@ -695,16 +687,16 @@ openclaw voicecall setup --json } ``` -Після зміни конфігурації перезапустіть або перезавантажте Gateway, потім виконайте: +Після зміни конфігурації перезапустіть або перезавантажте Gateway, а потім виконайте: ```bash openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` — це dry run, якщо не передати `--yes`. +`voicecall smoke` є пробним запуском, якщо не передано `--yes`. -### Не вдається перевірити облікові дані провайдера +### Облікові дані провайдера не працюють Перевірте вибраного провайдера та обов’язкові поля облікових даних: @@ -714,11 +706,11 @@ openclaw voicecall smoke `fromNumber`. - Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`. -Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки -не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить -своє середовище. +Облікові дані мають існувати на хості Gateway. Редагування локального профілю shell +не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє +середовище. -### Виклики запускаються, але Webhook-и провайдера не надходять +### Виклики запускаються, але Webhook провайдера не надходять Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу Webhook: @@ -726,7 +718,7 @@ openclaw voicecall smoke https://voice.example.com/voice/webhook ``` -Потім перевірте стан виконання: +Потім перевірте стан середовища виконання: ```bash openclaw voicecall status --call-id @@ -737,9 +729,9 @@ openclaw voicecall tail - `publicUrl` вказує на інший шлях, ніж `serve.path`. - URL тунелю змінився після запуску Gateway. -- Проксі пересилає запит, але видаляє або переписує заголовки host/proto. -- Брандмауер або DNS спрямовує публічне ім’я хоста кудись іще, а не до Gateway. -- Gateway було перезапущено без увімкненого Plugin Voice Call. +- Проксі пересилає запит, але вилучає або переписує заголовки host/proto. +- Firewall або DNS спрямовує публічне ім’я хоста кудись не до Gateway. +- Gateway було перезапущено без увімкненого плагіна Voice Call. Коли перед Gateway стоїть зворотний проксі або тунель, задайте `webhookSecurity.allowedHosts` як публічне ім’я хоста або використайте @@ -747,21 +739,21 @@ openclaw voicecall tail `webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під вашим контролем. -### Не вдається перевірити підпис +### Перевірка підпису не проходить Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює -з вхідного запиту. Якщо перевірка підписів не вдається: +з вхідного запиту. Якщо підписи не проходять перевірку: -- Переконайтеся, що URL Webhook провайдера точно відповідає `publicUrl`, включно зі +- Переконайтеся, що URL Webhook провайдера точно збігається з `publicUrl`, включно зі схемою, хостом і шляхом. -- Для URL-адрес безплатного рівня ngrok оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю. +- Для URL ngrok безкоштовного рівня оновлюйте `publicUrl`, коли ім’я хоста тунелю змінюється. - Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте `webhookSecurity.allowedHosts`. - Не вмикайте `skipSignatureVerification` поза локальним тестуванням. -### Збої підключення Google Meet через Twilio +### Приєднання Google Meet через Twilio не працює -Google Meet використовує цей Plugin для підключень через телефонний набір Twilio. Спочатку перевірте Voice Call: +Google Meet використовує цей плагін для приєднання через дозвон Twilio. Спочатку перевірте Voice Call: ```bash openclaw voicecall setup @@ -776,23 +768,23 @@ openclaw googlemeet setup --transport twilio Якщо Voice Call працює, але учасник Meet так і не приєднується, перевірте номер дозвону Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як -зустріч відхиляє або ігнорує неправильну DTMF-послідовність. +зустріч відхиляє або ігнорує неправильну послідовність DTMF. -Google Meet передає DTMF-послідовність Meet і вступний текст до `voicecall.start`. +Google Meet передає послідовність DTMF Meet і вступний текст до `voicecall.start`. Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, перенаправляє назад до -Webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ було -згенеровано після приєднання телефонного учасника до зустрічі. +Webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ було згенеровано +після приєднання телефонного учасника до зустрічі. -### У виклику реального часу немає мовлення +### У виклику в реальному часі немає мовлення Переконайтеся, що увімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно мати значення true. Для викликів Twilio у реальному часі також перевірте: -- Plugin провайдера реального часу завантажено та зареєстровано. +- Плагін провайдера реального часу завантажений і зареєстрований. - `realtime.provider` не задано або він називає зареєстрованого провайдера. -- Ключ API провайдера доступний процесу Gateway. +- API-ключ провайдера доступний процесу Gateway. - `openclaw voicecall tail` показує, що медіапотік прийнято, а провайдер реального часу готовий до початкового привітання. diff --git a/docs/uk/reference/secretref-credential-surface.md b/docs/uk/reference/secretref-credential-surface.md index e1b6ad364..3d03cf31d 100644 --- a/docs/uk/reference/secretref-credential-surface.md +++ b/docs/uk/reference/secretref-credential-surface.md @@ -1,25 +1,25 @@ --- read_when: - Перевірка покриття облікових даних SecretRef - - Аудит того, чи придатні облікові дані для `secrets configure` або `secrets apply` - - Перевірка, чому облікові дані виходять за межі підтримуваної поверхні + - Перевірка того, чи облікові дані придатні для `secrets configure` або `secrets apply` + - Перевірка, чому облікові дані перебувають поза підтримуваною поверхнею summary: Канонічна підтримувана й непідтримувана поверхня облікових даних SecretRef -title: Поверхня облікових даних SecretRef +title: Інтерфейс облікових даних SecretRef x-i18n: - generated_at: "2026-04-27T06:28:00Z" - model: gpt-5.4 + generated_at: "2026-05-01T06:25:06Z" + model: gpt-5.5 provider: openai - source_hash: b04902427e9851cc36c1dfd07ed44b46b55450c251075e9955af6696f08bc334 + source_hash: 41111ac82142c906005e0f585c86f2ff0b454afdaec07343c295e6b83571718e source_path: reference/secretref-credential-surface.md - workflow: 15 + workflow: 16 --- Ця сторінка визначає канонічну поверхню облікових даних SecretRef. -Намір сфери застосування: +Намір області застосування: -- У межах сфери: лише облікові дані, надані користувачем, які OpenClaw не створює і не ротує. -- Поза сферою: облікові дані, створені під час виконання або такі, що ротуються, матеріали оновлення OAuth і артефакти, подібні до сесій. +- У межах області: строго надані користувачем облікові дані, які OpenClaw не створює й не ротує. +- Поза областю: облікові дані, створені під час виконання або ротаційні, матеріали оновлення OAuth і артефакти, подібні до сесійних. ## Підтримувані облікові дані @@ -57,6 +57,8 @@ x-i18n: - `plugins.entries.firecrawl.config.webSearch.apiKey` - `plugins.entries.minimax.config.webSearch.apiKey` - `plugins.entries.tavily.config.webSearch.apiKey` +- `plugins.entries.voice-call.config.realtime.providers.*.apiKey` +- `plugins.entries.voice-call.config.streaming.providers.*.apiKey` - `plugins.entries.voice-call.config.tts.providers.*.apiKey` - `plugins.entries.voice-call.config.twilio.authToken` - `tools.web.search.apiKey` @@ -110,8 +112,8 @@ x-i18n: - `channels.zalo.webhookSecret` - `channels.zalo.accounts.*.botToken` - `channels.zalo.accounts.*.webhookSecret` -- `channels.googlechat.serviceAccount` через сусідній `serviceAccountRef` (виняток сумісності) -- `channels.googlechat.accounts.*.serviceAccount` через сусідній `serviceAccountRef` (виняток сумісності) +- `channels.googlechat.serviceAccount` через сусіднє поле `serviceAccountRef` (виняток сумісності) +- `channels.googlechat.accounts.*.serviceAccount` через сусіднє поле `serviceAccountRef` (виняток сумісності) ### Цілі `auth-profiles.json` (`secrets configure` + `secrets apply` + `secrets audit`) @@ -123,21 +125,21 @@ x-i18n: Примітки: - Цілі плану auth-profile потребують `agentId`. -- Записи плану націлюються на `profiles.*.key` / `profiles.*.token` і записують сусідні ref (`keyRef` / `tokenRef`). -- Ref auth-profile включено до runtime resolution і покриття audit. -- У `openclaw.json` SecretRef мають використовувати структуровані об’єкти на кшталт `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`. Застарілі рядки-маркери `secretref-env:` відхиляються на шляхах облікових даних SecretRef; запустіть `openclaw doctor --fix`, щоб мігрувати коректні маркери. -- Захист політики OAuth: `auth.profiles..mode = "oauth"` не можна поєднувати з входами SecretRef для цього профілю. Під час запуску/перезавантаження та розв’язання auth-profile відбувається негайна помилка, якщо цю політику порушено. -- Для провайдерів моделей, керованих SecretRef, згенеровані записи `agents/*/agent/models.json` зберігають маркери без секретів (а не розв’язані значення секретів) для поверхонь `apiKey`/header. -- Збереження маркерів є джерельно-авторитетним: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних runtime-значень секретів. +- Записи плану націлюються на `profiles.*.key` / `profiles.*.token` і записують сусідні посилання (`keyRef` / `tokenRef`). +- Посилання auth-profile включено до покриття розв’язання під час виконання та аудиту. +- В `openclaw.json` SecretRefs мають використовувати структуровані об’єкти, як-от `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`. Застарілі рядки-маркери `secretref-env:` відхиляються на шляхах облікових даних SecretRef; виконайте `openclaw doctor --fix`, щоб мігрувати чинні маркери. +- Захист політики OAuth: `auth.profiles..mode = "oauth"` не можна поєднувати з вхідними даними SecretRef для цього профілю. Запуск/перезавантаження та розв’язання auth-profile швидко завершуються помилкою, коли цю політику порушено. +- Для постачальників моделей, керованих SecretRef, згенеровані записи `agents/*/agent/models.json` зберігають несекретні маркери (а не розв’язані значення секретів) для поверхонь `apiKey`/заголовків. +- Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних секретних значень під час виконання. - Для вебпошуку: - - У режимі явного провайдера (задано `tools.web.search.provider`) активним є лише ключ вибраного провайдера. - - В автоматичному режимі (`tools.web.search.provider` не задано) активним є лише перший ключ провайдера, який розв’язується за пріоритетом. - - В автоматичному режимі ref провайдерів, які не вибрано, вважаються неактивними, доки їх не буде вибрано. - - Застарілі шляхи провайдера `tools.web.search.*` усе ще розв’язуються протягом вікна сумісності, але канонічна поверхня SecretRef — це `plugins.entries..config.webSearch.*`. + - У режимі явного постачальника (задано `tools.web.search.provider`) активним є лише ключ вибраного постачальника. + - В автоматичному режимі (`tools.web.search.provider` не задано) активним є лише перший ключ постачальника, який розв’язується за пріоритетом. + - В автоматичному режимі посилання невибраних постачальників вважаються неактивними, доки їх не буде вибрано. + - Застарілі шляхи постачальників `tools.web.search.*` усе ще розв’язуються протягом вікна сумісності, але канонічною поверхнею SecretRef є `plugins.entries..config.webSearch.*`. ## Непідтримувані облікові дані -Облікові дані поза сферою охоплюють: +Облікові дані поза областю включають: [//]: # "secretref-unsupported-list-start" @@ -155,9 +157,9 @@ x-i18n: Обґрунтування: -- Ці облікові дані є створюваними, ротованими, сесійними або належать до довготривалих класів OAuth, які не відповідають read-only зовнішньому розв’язанню SecretRef. +- Ці облікові дані належать до класів, які створюються, ротуються, містять сесійні дані або є довготривалими OAuth-даними, і не підходять для розв’язання лише для читання через зовнішній SecretRef. ## Пов’язане - [Керування секретами](/uk/gateway/secrets) -- [Семантика облікових даних auth](/uk/auth-credential-semantics) +- [Семантика облікових даних автентифікації](/uk/auth-credential-semantics)