chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
af701e79ae
commit
12353ea357
File diff suppressed because it is too large
Load Diff
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий виклик з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin голосових викликів
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокове транскрибування для телефонії
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з необов’язковою підтримкою голосового зв’язку в реальному часі та потокової транскрипції
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, за потреби з голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin для голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:59:45Z"
|
||||
generated_at: "2026-05-04T04:47:20Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
|
||||
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Голосові дзвінки для OpenClaw через plugin. Підтримує вихідні сповіщення,
|
||||
багатоетапні розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні дзвінки з політиками списку дозволених.
|
||||
Голосові виклики для OpenClaw через plugin. Підтримує вихідні сповіщення,
|
||||
багатокрокові розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками списку дозволених.
|
||||
|
||||
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Plugin голосових дзвінків працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
Voice Call plugin працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте plugin на машині, де працює
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
Gateway, а потім перезапустіть Gateway, щоб його завантажити.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
@ -48,25 +48,25 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Використовуйте пакет без версії, щоб слідувати поточному офіційному тегу релізу. Закріплюйте
|
||||
точну версію лише тоді, коли потрібна відтворювана інсталяція.
|
||||
Використовуйте пакет без версії, щоб відстежувати поточний офіційний тег релізу. Закріплюйте
|
||||
точну версію лише тоді, коли потрібне відтворюване встановлення.
|
||||
|
||||
Після цього перезапустіть Gateway, щоб plugin завантажився.
|
||||
|
||||
</Step>
|
||||
<Step title="Налаштуйте провайдера та webhook">
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (див.
|
||||
[Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні:
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
|
||||
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і публічно
|
||||
доступна URL-адреса webhook.
|
||||
доступний URL webhook.
|
||||
</Step>
|
||||
<Step title="Перевірте налаштування">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє
|
||||
увімкнення plugin, облікові дані провайдера, доступність webhook і те, що
|
||||
Стандартний вивід зручно читати в чат-журналах і терміналах. Він перевіряє
|
||||
ввімкнення plugin, облікові дані провайдера, доступність webhook і те, що
|
||||
активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
`--json` для скриптів.
|
||||
|
||||
@ -77,8 +77,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Обидві команди за замовчуванням виконуються без реальних дій. Додайте `--yes`, щоб справді здійснити короткий
|
||||
вихідний дзвінок-сповіщення:
|
||||
Обидві команди за замовчуванням виконуються як dry run. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний виклик-сповіщення:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -88,21 +88,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса webhook**.
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначати **публічний URL webhook**.
|
||||
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
|
||||
визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати webhook від оператора.
|
||||
визначається як loopback чи приватний мережевий простір, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати carrier webhooks.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
|
||||
пропускає запуск runtime. Команди, RPC-виклики та інструменти агента все одно
|
||||
пропускає запуск runtime. Команди, RPC-виклики й інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
|
||||
<Note>
|
||||
Облікові дані 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).
|
||||
Облікові дані 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).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -175,28 +175,28 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Примітки щодо доступності та безпеки провайдера">
|
||||
- Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси webhook.
|
||||
- `mock` — локальний провайдер для розробки (без мережевих викликів).
|
||||
<Accordion title="Нотатки про доступність провайдера та безпеку">
|
||||
- Twilio, Telnyx і Plivo потребують **публічно доступного** URL webhook.
|
||||
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
|
||||
- `skipSignatureVerification` призначено лише для локального тестування.
|
||||
- На безплатному рівні ngrok задайте `publicUrl` як точну URL-адресу ngrok; перевірка підпису завжди застосовується.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безплатного рівня ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для production віддавайте перевагу стабільному домену або funnel Tailscale.
|
||||
- На безкоштовному тарифі ngrok задайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусова.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Twilio webhooks з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL безкоштовного тарифу Ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ліміти потокових підключень">
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувані + активні).
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані pre-start сокети для кожної вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів media stream (pending + active).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Міграції застарілої конфігурації">
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI у `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Резервний runtime поки що все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — `openclaw doctor --fix`, а shim сумісності є
|
||||
Старіші конфігурації з `provider: "log"`, `twilio.from` або застарілими
|
||||
ключами OpenAI `streaming.*` переписуються командою `openclaw doctor --fix`.
|
||||
Runtime fallback поки що приймає старі ключі voice-call, але
|
||||
шлях переписування — `openclaw doctor --fix`, а compat shim є
|
||||
тимчасовим.
|
||||
|
||||
Автоматично мігровані ключі streaming:
|
||||
@ -212,51 +212,54 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
## Область сесії
|
||||
|
||||
За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, щоб повторні дзвінки від
|
||||
того самого абонента зберігали пам’ять розмови. Установіть `sessionScope: "per-call"`, коли
|
||||
кожен дзвінок оператора має починатися зі свіжим контекстом, наприклад для рецепції,
|
||||
бронювання, IVR або потоків мосту Google Meet, де той самий номер телефону може
|
||||
За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, тому повторні виклики від
|
||||
того самого абонента зберігають пам’ять розмови. Задайте `sessionScope: "per-call"`, коли
|
||||
кожен carrier call має починатися зі свіжого контексту, наприклад для рецепції,
|
||||
бронювання, IVR або потоків моста Google Meet, де один і той самий номер телефону може
|
||||
представляти різні зустрічі.
|
||||
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає провайдера повнодуплексного голосу в реальному часі для live-аудіо
|
||||
дзвінка. Це окремо від `streaming`, який лише передає аудіо
|
||||
`realtime` вибирає повнодуплексного голосового провайдера в реальному часі для живого аудіо
|
||||
виклику. Це окремо від `streaming`, який лише передає аудіо
|
||||
провайдерам транскрипції в реальному часі.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
|
||||
аудіорежим для кожного дзвінка.
|
||||
аудіорежим для кожного виклику.
|
||||
</Warning>
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `realtime.enabled` підтримується для Twilio Media Streams.
|
||||
- `realtime.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
|
||||
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми plugin провайдерів.
|
||||
- Сира конфігурація, що належить провайдеру, міститься в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням надає спільний інструмент `openclaw_agent_consult` у реальному часі. Модель реального часу може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає проіндексовану пам’ять/контекст сесії для consult-запитання та повертає ці фрагменти моделі реального часу в межах `realtime.fastContext.timeoutMs`, перш ніж відкотитися до повного consult-агента лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жодного провайдера голосу в реальному часі не зареєстровано, Voice Call записує попередження та пропускає realtime-медіа замість збою всього plugin.
|
||||
- Ключі consult-сесії повторно використовують збережену сесію дзвінка, коли вона доступна, а потім відкочуються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих дзвінків).
|
||||
- `realtime.provider` необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого голосового провайдера в реальному часі.
|
||||
- Вбудовані голосові провайдери в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider plugins.
|
||||
- Сирий конфіг, яким володіє провайдер, розміщується в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням відкриває спільний realtime-інструмент `openclaw_agent_consult`. Realtime-модель може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw.
|
||||
- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає індексовану пам’ять/контекст сесії для consult-запитання та повертає ці фрагменти realtime-моделі протягом `realtime.fastContext.timeoutMs`, перш ніж переходити до повного consult-агента, лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жодного голосового провайдера в реальному часі не зареєстровано, Voice Call записує попередження та пропускає realtime media замість того, щоб зупиняти весь plugin з помилкою.
|
||||
- Ключі consult-сесії повторно використовують збережену сесію виклику, коли вона доступна, а потім повертаються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих викликів).
|
||||
|
||||
### Політика інструментів
|
||||
|
||||
`realtime.toolPolicy` керує запуском consult:
|
||||
`realtime.toolPolicy` керує consult-запуском:
|
||||
|
||||
| Політика | Поведінка |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати стандартну політику інструментів агента. |
|
||||
| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` усе одно передаються провайдеру реального часу. |
|
||||
| `safe-read-only` | Відкрити consult-інструмент і обмежити звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Відкрити consult-інструмент і дозволити звичайному агенту використовувати стандартну політику інструментів агента. |
|
||||
| `none` | Не відкривати consult-інструмент. Користувацькі `realtime.tools` все одно передаються realtime-провайдеру. |
|
||||
|
||||
### Приклади провайдерів реального часу
|
||||
### Приклади realtime-провайдерів
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
Типові значення: API-ключ із `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY` або `GOOGLE_GENERATIVE_AI_API_KEY`; модель
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025`; голос `Kore`.
|
||||
`sessionResumption` і `contextWindowCompression` за замовчуванням увімкнені для довших,
|
||||
відновлюваних викликів. Використовуйте `silenceDurationMs`, `startSensitivity` і
|
||||
`endSensitivity`, щоб налаштувати швидше передавання черги мовлення для телефонного аудіо.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -277,6 +280,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
model: "gemini-2.5-flash-native-audio-preview-12-2025",
|
||||
voice: "Kore",
|
||||
silenceDurationMs: 500,
|
||||
startSensitivity: "high",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -311,21 +316,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai) для параметрів голосу в реальному часі,
|
||||
Див. [провайдер Google](/uk/providers/google) та
|
||||
[провайдер OpenAI](/uk/providers/openai) щодо параметрів голосу в реальному часі,
|
||||
специфічних для провайдера.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для live-аудіо дзвінка.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для аудіо живого дзвінка.
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `streaming.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Сирова конфігурація, що належить провайдеру, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення потоку `start`, Voice Call негайно реєструє потік, ставить вхідні медіадані в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб завершити роботу всього плагіна з помилкою.
|
||||
- `streaming.provider` необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) та xAI (`xai`), зареєстровані їхніми provider plugins.
|
||||
- Сирий конфіг, що належить провайдеру, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надішле прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб завершити весь plugin з помилкою.
|
||||
|
||||
### Приклади провайдерів потокового передавання
|
||||
|
||||
@ -364,7 +369,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
<Tab title="xAI">
|
||||
Типові значення: API-ключ `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
|
||||
кінцева точка `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
|
||||
endpoint `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
|
||||
`endpointingMs: 800`; `interimResults: true`.
|
||||
|
||||
```json5
|
||||
@ -395,10 +400,10 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## TTS для викликів
|
||||
## TTS для дзвінків
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації плагіна з
|
||||
мовлення під час дзвінків. Її можна перевизначити в конфігу plugin з
|
||||
**такою самою формою** — вона глибоко об’єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
@ -416,22 +421,22 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонне аудіо потребує PCM;
|
||||
поточний транспорт Microsoft не надає телефонний PCM-вивід.
|
||||
**Microsoft speech ігнорується для голосових дзвінків.** Телефонному аудіо потрібен PCM;
|
||||
поточний транспорт Microsoft не надає вихід PCM для телефонії.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації плагіна (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Core 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`) для налагодження.
|
||||
- Коли barge-in Twilio або демонтаж потоку очищає чергу TTS, відкладені запити на відтворення завершуються, а не залишають абонентів очікувати завершення відтворення.
|
||||
- Коли barge-in Twilio або розбір потоку очищує чергу TTS в очікуванні, запити відтворення в черзі завершуються, а не залишають абонентів чекати завершення відтворення.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Core TTS only">
|
||||
<Tab title="Лише Core TTS">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -445,7 +450,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
<Tab title="Перевизначення на ElevenLabs (лише дзвінки)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -469,7 +474,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке об’єднання)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -493,9 +498,9 @@ Voice Call використовує основну конфігурацію `mes
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Вхідні виклики
|
||||
## Вхідні дзвінки
|
||||
|
||||
Вхідна політика за замовчуванням має значення `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
Для вхідної політики типове значення — `disabled`. Щоб увімкнути вхідні дзвінки, задайте:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -506,33 +511,21 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller-ID із низьким рівнем гарантії. Плагін
|
||||
нормалізує надане провайдером значення `From` і порівнює його з
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і
|
||||
цілісність payload, але вона **не** доводить право власності на номер
|
||||
абонента PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller-ID, а не як надійну
|
||||
ідентичність абонента.
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller-ID з низьким рівнем надійності. Plugin нормалізує надане провайдером значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку провайдером і цілісність payload, але **не** доводить право власності на номер абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller-ID, а не як надійну ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте їх за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему agent. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Маршрутизація за номером
|
||||
|
||||
Використовуйте `numbers`, коли один плагін Voice Call приймає виклики для кількох телефонних
|
||||
номерів і кожен номер має поводитися як окрема лінія. Наприклад, один
|
||||
номер може використовувати невимушеного персонального асистента, а інший — бізнес-персону,
|
||||
іншого агента відповіді та інший голос TTS.
|
||||
Використовуйте `numbers`, коли один Voice Call plugin приймає дзвінки для кількох телефонних номерів і кожен номер має поводитися як окрема лінія. Наприклад, один номер може використовувати неформального персонального асистента, а інший — бізнес-персону, іншого agent для відповіді та інший голос TTS.
|
||||
|
||||
Маршрути вибираються з наданого провайдером набраного номера `To`. Ключі мають бути
|
||||
номерами E.164. Коли надходить виклик, Voice Call один раз визначає відповідний маршрут,
|
||||
зберігає зіставлений маршрут у записі виклику та повторно використовує цю ефективну конфігурацію
|
||||
для привітання, класичного шляху автовідповіді, шляху консультації в реальному часі та
|
||||
відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальна конфігурація Voice Call.
|
||||
Вихідні виклики не використовують `numbers`; передавайте вихідну ціль, повідомлення та
|
||||
сеанс явно під час ініціювання виклику.
|
||||
Маршрути вибираються з наданого провайдером набраного номера `To`. Ключі мають бути номерами E.164. Коли надходить дзвінок, Voice Call один раз визначає відповідний маршрут, зберігає знайдений маршрут у записі дзвінка та повторно використовує цей ефективний конфіг для привітання, класичного шляху автовідповіді, шляху консультації в реальному часі та відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальний конфіг Voice Call.
|
||||
Вихідні дзвінки не використовують `numbers`; передавайте вихідну ціль, повідомлення та
|
||||
сесію явно під час ініціювання дзвінка.
|
||||
|
||||
Перевизначення маршрутів наразі підтримують:
|
||||
Перевизначення маршруту наразі підтримують:
|
||||
|
||||
- `inboundGreeting`
|
||||
- `tts`
|
||||
@ -541,8 +534,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
Значення маршруту `tts` глибоко об’єднується поверх глобальної конфігурації Voice Call `tts`, тож
|
||||
зазвичай можна перевизначити лише голос провайдера:
|
||||
Значення маршруту `tts` глибоко об’єднується поверх глобального конфігу Voice Call `tts`, тож зазвичай можна перевизначити лише голос провайдера:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -568,9 +560,9 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
|
||||
### Контракт мовного виводу
|
||||
### Контракт мовленнєвого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає до системного prompt суворий контракт мовного виводу:
|
||||
Для автовідповідей Voice Call додає до системного prompt суворий контракт мовленнєвого виводу:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
@ -578,42 +570,39 @@ Voice Call використовує основну конфігурацію `mes
|
||||
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує payloads, позначені як вміст reasoning/error.
|
||||
- Розбирає прямий JSON, fenced JSON або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаданих.
|
||||
- Ігнорує payload, позначені як вміст reasoning/error.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту та видаляє ймовірні вступні абзаци планування/метаданих.
|
||||
|
||||
Це зосереджує мовне відтворення на тексті для абонента й запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
Це утримує мовленнєве відтворення сфокусованим на тексті для абонента й запобігає
|
||||
витоку тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до поточного
|
||||
стану відтворення:
|
||||
Для вихідних дзвінків `conversation` обробка першого повідомлення прив’язана до стану живого відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Очищення черги barge-in та автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується помилкою, дзвінок повертається до `listening`, а початкове повідомлення лишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio запускається під час підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає записи Twilio TTS, які вже стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжити роботу без очікування аудіо, яке ніколи не буде відтворено.
|
||||
- Голосові розмови в реальному часі використовують власний початковий хід потоку в реальному часі. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тож вихідні сеанси `<Connect><Stream>` залишаються приєднаними.
|
||||
- Barge-in перериває активне відтворення й очищує записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Голосові розмови в реальному часі використовують власний початковий turn потоку в реальному часі. Voice Call **не** надсилає legacy-оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сесії `<Connect><Stream>` лишаються підключеними.
|
||||
|
||||
### Grace-період відключення потоку Twilio
|
||||
### Пільговий період відключення потоку Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед
|
||||
автоматичним завершенням виклику:
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 ms** перед
|
||||
автоматичним завершенням дзвінка:
|
||||
|
||||
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після grace-періоду жоден потік не реєструється повторно, виклик завершується, щоб уникнути завислих активних викликів.
|
||||
- Якщо потік повторно підключається протягом цього вікна, автозавершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не реєструється повторно, дзвінок завершується, щоб запобігти завислим активним дзвінкам.
|
||||
|
||||
## Reaper застарілих викликів
|
||||
## Прибирач застарілих дзвінків
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
webhook (наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення
|
||||
— `0` (вимкнено).
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати дзвінки, які ніколи не отримують термінальний webhook (наприклад, дзвінки в notify-режимі, які ніколи не завершуються). Типове значення — `0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі notify.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
- **Production:** `120`–`300` секунд для потоків notify-типу.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні дзвінки могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -632,28 +621,26 @@ webhook (наприклад, виклики в режимі notify, які ні
|
||||
|
||||
## Безпека Webhook
|
||||
|
||||
Коли proxy або tunnel розміщено перед Gateway, плагін
|
||||
реконструює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
керують тим, яким forwarded-заголовкам довіряти:
|
||||
Коли proxy або tunnel розміщено перед Gateway, plugin реконструює публічний URL для перевірки підпису. Ці параметри керують тим, яким forwarded-заголовкам довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Allowlist хостів із forwarding-заголовків.
|
||||
Список дозволених host з forwarding-заголовків.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряти forwarded-заголовкам без allowlist.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
|
||||
Довіряти forwarded-заголовкам лише тоді, коли віддалений IP запиту збігається зі списком.
|
||||
</ParamField>
|
||||
|
||||
Додаткові захисти:
|
||||
Додаткові засоби захисту:
|
||||
|
||||
- **Захист від replay** Webhook увімкнено для Twilio і Plivo. Повторно відтворені чинні webhook-запити підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах `<Gather>`, тому застарілі/повторно відтворені speech callback-виклики не можуть задовольнити новіший очікуваний хід транскрипта.
|
||||
- Неавтентифіковані webhook-запити відхиляються до читання тіла, якщо обов’язкові заголовки підпису провайдера відсутні.
|
||||
- Webhook voice-call використовує спільний pre-auth body profile (64 КБ / 5 секунд) плюс обмеження кількості одночасних запитів для кожної IP-адреси перед перевіркою підпису.
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio та Plivo. Повторно відтворені дійсні webhook-запити підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Conversation turns Twilio містять токен для кожного turn у callbacks `<Gather>`, тож застарілі/повторно відтворені мовленнєві callbacks не можуть задовольнити новіший очікуваний transcript turn.
|
||||
- Неавтентифіковані webhook-запити відхиляються до читання body, якщо відсутні потрібні signature-заголовки провайдера.
|
||||
- Webhook voice-call використовує спільний pre-auth body profile (64 KB / 5 seconds) плюс per-IP in-flight cap перед перевіркою підпису.
|
||||
|
||||
Приклад зі стабільним публічним хостом:
|
||||
Приклад зі стабільним публічним host:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -687,15 +674,15 @@ openclaw voicecall latency # summarize turn latency from lo
|
||||
openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Коли Gateway уже запущено, операційні команди `voicecall` делегуються
|
||||
runtime voice-call, що належить Gateway, щоб CLI не прив’язував другий
|
||||
webhook-сервер. Якщо Gateway недоступний, команди повертаються до
|
||||
Коли Gateway вже запущено, операційні команди `voicecall` делегують
|
||||
runtime голосового виклику, яким володіє Gateway, щоб CLI не прив’язував другий
|
||||
сервер webhook. Якщо жоден Gateway недоступний, команди повертаються до
|
||||
автономного runtime CLI.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища голосових викликів.
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху зберігання голосових викликів.
|
||||
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (за замовчуванням 200). Вивід містить p50/p90/p99
|
||||
для затримки ходу та часу очікування прослуховування.
|
||||
для затримки ходу й часу очікування прослуховування.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
@ -710,11 +697,11 @@ webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
Цей репозиторій постачається з відповідним документом skill у `skills/voice-call/SKILL.md`.
|
||||
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## Gateway RPC
|
||||
## RPC Gateway
|
||||
|
||||
| Метод | Аргументи |
|
||||
| Метод | Аргументи |
|
||||
| -------------------- | ------------------------------------------ |
|
||||
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
|
||||
| `voicecall.continue` | `callId`, `message` |
|
||||
@ -723,15 +710,15 @@ webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі сповіщення
|
||||
`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в notify-mode
|
||||
мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні
|
||||
цифри після з’єднання.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
### Налаштування не проходить перевірку експонування Webhook
|
||||
### Налаштуванню не вдається оприлюднити Webhook
|
||||
|
||||
Запустіть налаштування з того самого середовища, у якому працює Gateway:
|
||||
Запускайте налаштування з того самого середовища, у якому працює Gateway:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
@ -739,18 +726,18 @@ 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`.
|
||||
|
||||
Вихідні виклики Twilio в режимі сповіщення надсилають початковий `<Say>` TwiML безпосередньо в
|
||||
запиті create-call, тому перше озвучене повідомлення не залежить від того, чи Twilio
|
||||
отримає Webhook TwiML. Публічний Webhook усе ще потрібен для статусних зворотних викликів,
|
||||
розмовних викликів, DTMF перед з’єднанням, потоків реального часу та керування викликом
|
||||
Вихідні виклики Twilio у notify-mode надсилають свій початковий `<Say>` TwiML безпосередньо в
|
||||
запит create-call, тому перше озвучене повідомлення не залежить від того, чи Twilio
|
||||
отримає webhook TwiML. Публічний Webhook усе ще потрібен для callback-ів стану,
|
||||
розмовних викликів, DTMF до з’єднання, потоків реального часу й керування викликом
|
||||
після з’єднання.
|
||||
|
||||
Використовуйте один шлях публічного експонування:
|
||||
Використовуйте один шлях публічного доступу:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -770,18 +757,18 @@ openclaw voicecall setup --json
|
||||
}
|
||||
```
|
||||
|
||||
Після зміни конфігурації перезапустіть або перезавантажте Gateway, потім виконайте:
|
||||
Після зміни конфігурації перезапустіть або перезавантажте Gateway, а потім виконайте:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` є пробним запуском, якщо не передати `--yes`.
|
||||
`voicecall smoke` є пробним запуском, якщо ви не передасте `--yes`.
|
||||
|
||||
### Облікові дані провайдера не працюють
|
||||
### Облікові дані провайдера не проходять перевірку
|
||||
|
||||
Перевірте вибраного провайдера та потрібні поля облікових даних:
|
||||
Перевірте вибраного провайдера й обов’язкові поля облікових даних:
|
||||
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber`, або
|
||||
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`.
|
||||
@ -789,19 +776,19 @@ openclaw voicecall smoke
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`.
|
||||
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє
|
||||
середовище.
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального shell-профілю
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить
|
||||
своє середовище.
|
||||
|
||||
### Виклики запускаються, але Webhook провайдера не надходять
|
||||
### Виклики починаються, але Webhook-и провайдера не надходять
|
||||
|
||||
Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу Webhook:
|
||||
Підтвердьте, що консоль провайдера вказує на точну публічну URL-адресу Webhook:
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
```
|
||||
|
||||
Потім перевірте стан виконання:
|
||||
Потім перевірте стан runtime:
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
@ -811,33 +798,33 @@ openclaw logs --follow
|
||||
|
||||
Поширені причини:
|
||||
|
||||
- `publicUrl` вказує на інший шлях, ніж `serve.path`.
|
||||
- `publicUrl` указує на інший шлях, ніж `serve.path`.
|
||||
- URL тунелю змінився після запуску Gateway.
|
||||
- Проксі пересилає запит, але видаляє або переписує заголовки host/proto.
|
||||
- Брандмауер або DNS спрямовує публічне ім’я хоста кудись не на Gateway.
|
||||
- Firewall або DNS спрямовує публічне ім’я хоста кудись інде, а не до Gateway.
|
||||
- Gateway було перезапущено без увімкненого Plugin Voice Call.
|
||||
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, задайте
|
||||
`webhookSecurity.allowedHosts` як публічне ім’я хоста або використайте
|
||||
Коли перед Gateway стоїть reverse proxy або тунель, установіть
|
||||
`webhookSecurity.allowedHosts` на публічне ім’я хоста або використовуйте
|
||||
`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте
|
||||
`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під
|
||||
вашим контролем.
|
||||
|
||||
### Перевірка підпису не вдається
|
||||
### Перевірка підпису не проходить
|
||||
|
||||
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює
|
||||
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відновлює
|
||||
з вхідного запиту. Якщо підписи не проходять перевірку:
|
||||
|
||||
- Переконайтеся, що URL Webhook провайдера точно відповідає `publicUrl`, включно зі
|
||||
- Підтвердьте, що URL Webhook провайдера точно збігається з `publicUrl`, включно зі
|
||||
схемою, хостом і шляхом.
|
||||
- Для URL безплатного рівня ngrok оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю.
|
||||
- Переконайтеся, що проксі зберігає оригінальні заголовки host і proto, або налаштуйте
|
||||
- Для URL безкоштовного рівня ngrok оновлюйте `publicUrl`, коли ім’я хоста тунелю змінюється.
|
||||
- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- Не вмикайте `skipSignatureVerification` поза локальним тестуванням.
|
||||
|
||||
### Приєднання Google Meet через Twilio не вдаються
|
||||
### Приєднання Google Meet Twilio не вдаються
|
||||
|
||||
Google Meet використовує цей Plugin для приєднань через набір номера Twilio. Спершу перевірте Voice Call:
|
||||
Google Meet використовує цей Plugin для приєднань Twilio через dial-in. Спочатку перевірте Voice Call:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
@ -850,43 +837,43 @@ openclaw voicecall smoke --to "+15555550123"
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Якщо Voice Call зелений, але учасник Meet так і не приєднується, перевірте номер набору
|
||||
Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
|
||||
Якщо Voice Call зелений, але учасник Meet так і не приєднується, перевірте номер
|
||||
dial-in Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
|
||||
зустріч відхиляє або ігнорує неправильну послідовність DTMF.
|
||||
|
||||
Google Meet передає послідовність DTMF Meet і вступний текст до `voicecall.start`.
|
||||
Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, перенаправляє назад до
|
||||
Webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ був згенерований
|
||||
Для викликів Twilio Voice Call спершу обслуговує DTMF TwiML, перенаправляє назад до
|
||||
Webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ генерувався
|
||||
після того, як телефонний учасник приєднався до зустрічі.
|
||||
|
||||
Використовуйте `openclaw logs --follow` для живого трасування фази. Успішне приєднання
|
||||
Використовуйте `openclaw logs --follow` для трасування живої фази. Справне приєднання
|
||||
Twilio Meet записує журнали в такому порядку:
|
||||
|
||||
- Google Meet делегує приєднання Twilio до Voice Call.
|
||||
- Voice Call зберігає DTMF TwiML перед з’єднанням.
|
||||
- Початковий TwiML Twilio споживається та віддається перед обробкою реального часу.
|
||||
- Voice Call віддає TwiML реального часу для виклику Twilio.
|
||||
- Voice Call зберігає DTMF TwiML до з’єднання.
|
||||
- Початковий TwiML Twilio споживається й обслуговується перед обробкою реального часу.
|
||||
- Voice Call обслуговує TwiML реального часу для виклику Twilio.
|
||||
- Міст реального часу запускається з початковим привітанням у черзі.
|
||||
|
||||
`openclaw voicecall tail` усе ще показує збережені записи викликів; це корисно для
|
||||
стану виклику та транскриптів, але не кожен перехід Webhook/реального часу з’являється
|
||||
там.
|
||||
стану виклику й транскриптів, але не кожен Webhook-перехід або перехід реального часу
|
||||
з’являється там.
|
||||
|
||||
### У виклику реального часу немає мовлення
|
||||
### Виклик реального часу не має мовлення
|
||||
|
||||
Переконайтеся, що увімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно бути true.
|
||||
Підтвердьте, що ввімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно бути `true`.
|
||||
|
||||
Для викликів Twilio реального часу також перевірте:
|
||||
Для викликів Twilio у реальному часі також перевірте:
|
||||
|
||||
- Plugin провайдера реального часу завантажений і зареєстрований.
|
||||
- `realtime.provider` не заданий або називає зареєстрованого провайдера.
|
||||
- Plugin провайдера реального часу завантажено й зареєстровано.
|
||||
- `realtime.provider` не встановлено або називає зареєстрованого провайдера.
|
||||
- API-ключ провайдера доступний процесу Gateway.
|
||||
- `openclaw logs --follow` показує, що TwiML реального часу віддано, міст реального часу
|
||||
- `openclaw logs --follow` показує, що TwiML реального часу обслуговано, міст реального часу
|
||||
запущено, а початкове привітання поставлено в чергу.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Перетворення тексту на мовлення](/uk/tools/tts)
|
||||
- [Text-to-speech](/uk/tools/tts)
|
||||
- [Голосове пробудження](/uk/nodes/voicewake)
|
||||
|
||||
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі Google Gemini з OpenClaw
|
||||
- Потрібен API-ключ або потік автентифікації OAuth
|
||||
summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіаконтенту, TTS, вебпошук)
|
||||
- Вам потрібен ключ API або потік автентифікації OAuth
|
||||
summary: Налаштування Google Gemini (ключ API + OAuth, генерування зображень, розуміння медіа, TTS, вебпошук)
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T04:47:18Z"
|
||||
generated_at: "2026-05-04T04:47:11Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
|
||||
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
|
||||
source_path: providers/google.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Plugin Google надає доступ до моделей Gemini через Google AI Studio, а також
|
||||
The Google Plugin надає доступ до моделей Gemini через Google AI Studio, а також
|
||||
генерацію зображень, розуміння медіа (зображення/аудіо/відео), перетворення тексту на мовлення та вебпошук через
|
||||
Gemini Grounding.
|
||||
|
||||
- Постачальник: `google`
|
||||
- Провайдер: `google`
|
||||
- Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
|
||||
- API: Google Gemini API
|
||||
- Опція середовища виконання: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
повторно використовує OAuth Gemini CLI, зберігаючи посилання на моделі канонічними як `google/*`.
|
||||
- Параметр середовища виконання: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
повторно використовує OAuth Gemini CLI, зберігаючи канонічні посилання на моделі як `google/*`.
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний метод автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ключ API">
|
||||
<Tab title="API key">
|
||||
**Найкраще для:** стандартного доступу до Gemini API через Google AI Studio.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть первинне налаштування">
|
||||
<Step title="Run onboarding">
|
||||
```bash
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
@ -46,7 +46,7 @@ Gemini Grounding.
|
||||
--gemini-api-key "$GEMINI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Установіть модель за замовчуванням">
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -57,7 +57,7 @@ Gemini Grounding.
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Verify the model is available">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
@ -65,21 +65,21 @@ Gemini Grounding.
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` підтримуються обидві. Використовуйте ту, яку вже налаштовано.
|
||||
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яку вже налаштовано.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI (OAuth)">
|
||||
**Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API.
|
||||
**Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого API-ключа.
|
||||
|
||||
<Warning>
|
||||
Постачальник `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
|
||||
повідомляють про обмеження облікових записів під час використання OAuth таким способом. Використовуйте на власний ризик.
|
||||
Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
|
||||
повідомляють про обмеження облікових записів під час використання OAuth у такий спосіб. Використовуйте на власний ризик.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть Gemini CLI">
|
||||
<Step title="Install the Gemini CLI">
|
||||
Локальна команда `gemini` має бути доступною в `PATH`.
|
||||
|
||||
```bash
|
||||
@ -90,26 +90,26 @@ Gemini Grounding.
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
OpenClaw підтримує як інсталяції Homebrew, так і глобальні інсталяції npm, зокрема
|
||||
поширені компонування Windows/npm.
|
||||
OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення npm, зокрема
|
||||
поширені макети Windows/npm.
|
||||
</Step>
|
||||
<Step title="Увійдіть через OAuth">
|
||||
<Step title="Log in via OAuth">
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Verify the model is available">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
- Модель за замовчуванням: `google/gemini-3.1-pro-preview`
|
||||
- Стандартна модель: `google/gemini-3.1-pro-preview`
|
||||
- Середовище виконання: `google-gemini-cli`
|
||||
- Псевдонім: `gemini-cli`
|
||||
|
||||
Ідентифікатор моделі Gemini 3.1 Pro у Gemini API — `gemini-3.1-pro-preview`. OpenClaw приймає коротший `google/gemini-3.1-pro` як зручний псевдонім і нормалізує його перед викликами постачальника.
|
||||
Ідентифікатор моделі Gemini API для Gemini 3.1 Pro — `gemini-3.1-pro-preview`. OpenClaw приймає коротший `google/gemini-3.1-pro` як зручний псевдонім і нормалізує його перед викликами провайдера.
|
||||
|
||||
**Змінні середовища:**
|
||||
|
||||
@ -119,13 +119,13 @@ Gemini Grounding.
|
||||
(Або варіанти `GEMINI_CLI_*`.)
|
||||
|
||||
<Note>
|
||||
Якщо запити OAuth Gemini CLI після входу завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або
|
||||
Якщо запити OAuth Gemini CLI не виконуються після входу, задайте `GOOGLE_CLOUD_PROJECT` або
|
||||
`GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Якщо вхід завершується помилкою до запуску потоку браузера, переконайтеся, що локальна команда `gemini`
|
||||
установлена й доступна в `PATH`.
|
||||
встановлена й доступна в `PATH`.
|
||||
</Note>
|
||||
|
||||
Посилання на моделі `google-gemini-cli/*` є застарілими псевдонімами сумісності. Нові
|
||||
@ -137,24 +137,24 @@ Gemini Grounding.
|
||||
|
||||
## Можливості
|
||||
|
||||
| Можливість | Підтримується |
|
||||
| ---------------------- | ---------------------------- |
|
||||
| Завершення чату | Так |
|
||||
| Генерація зображень | Так |
|
||||
| Генерація музики | Так |
|
||||
| Перетворення тексту на мовлення | Так |
|
||||
| Можливість | Підтримка |
|
||||
| --------------------- | ----------------------------- |
|
||||
| Чат-доповнення | Так |
|
||||
| Генерація зображень | Так |
|
||||
| Генерація музики | Так |
|
||||
| Перетворення тексту на мовлення | Так |
|
||||
| Голос у реальному часі | Так (Google Live API) |
|
||||
| Розуміння зображень | Так |
|
||||
| Транскрипція аудіо | Так |
|
||||
| Розуміння відео | Так |
|
||||
| Вебпошук (Grounding) | Так |
|
||||
| Мислення/міркування | Так (Gemini 2.5+ / Gemini 3+) |
|
||||
| Моделі Gemma 4 | Так |
|
||||
| Розуміння зображень | Так |
|
||||
| Транскрибування аудіо | Так |
|
||||
| Розуміння відео | Так |
|
||||
| Вебпошук (Grounding) | Так |
|
||||
| Мислення/міркування | Так (Gemini 2.5+ / Gemini 3+) |
|
||||
| Моделі Gemma 4 | Так |
|
||||
|
||||
## Вебпошук
|
||||
|
||||
Вбудований постачальник вебпошуку `gemini` використовує Gemini Google Search grounding.
|
||||
Налаштуйте спеціальний ключ пошуку в `plugins.entries.google.config.webSearch`
|
||||
Вбудований провайдер вебпошуку `gemini` використовує grounding Google Search у Gemini.
|
||||
Налаштуйте окремий ключ пошуку в `plugins.entries.google.config.webSearch`
|
||||
або дозвольте повторно використовувати `models.providers.google.apiKey` після `GEMINI_API_KEY`:
|
||||
|
||||
```json5
|
||||
@ -175,32 +175,32 @@ Gemini Grounding.
|
||||
}
|
||||
```
|
||||
|
||||
Пріоритет облікових даних такий: спеціальний `webSearch.apiKey`, потім `GEMINI_API_KEY`,
|
||||
потім `models.providers.google.apiKey`. `webSearch.baseUrl` необов’язковий і
|
||||
Пріоритет облікових даних: окремий `webSearch.apiKey`, потім `GEMINI_API_KEY`,
|
||||
потім `models.providers.google.apiKey`. `webSearch.baseUrl` є необов’язковим і
|
||||
існує для операторських проксі або сумісних кінцевих точок Gemini API; якщо його пропущено,
|
||||
вебпошук Gemini повторно використовує `models.providers.google.baseUrl`. Див.
|
||||
[пошук Gemini](/uk/tools/gemini-search), щоб дізнатися про поведінку інструмента, специфічну для постачальника.
|
||||
[Пошук Gemini](/uk/tools/gemini-search) щодо поведінки інструмента, специфічної для провайдера.
|
||||
|
||||
<Tip>
|
||||
Моделі Gemini 3 використовують `thinkingLevel`, а не `thinkingBudget`. OpenClaw зіставляє
|
||||
керування міркуваннями для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` із
|
||||
`thinkingLevel`, щоб запуски за замовчуванням або з низькою затримкою не надсилали вимкнені
|
||||
Моделі Gemini 3 використовують `thinkingLevel` замість `thinkingBudget`. OpenClaw зіставляє
|
||||
керування міркуванням для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з
|
||||
`thinkingLevel`, щоб стандартні запуски або запуски з низькою затримкою не надсилали вимкнені
|
||||
значення `thinkingBudget`.
|
||||
|
||||
`/think adaptive` зберігає семантику динамічного мислення Google замість вибору
|
||||
фіксованого рівня OpenClaw. Gemini 3 і Gemini 3.1 пропускають фіксований `thinkingLevel`, щоб
|
||||
фіксованого рівня OpenClaw. Gemini 3 і Gemini 3.1 не задають фіксований `thinkingLevel`, щоб
|
||||
Google міг вибрати рівень; Gemini 2.5 надсилає динамічний sentinel Google
|
||||
`thinkingBudget: -1`.
|
||||
|
||||
Моделі Gemma 4 (наприклад `gemma-4-26b-a4b-it`) підтримують режим мислення. OpenClaw
|
||||
переписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4.
|
||||
Установлення мислення в `off` зберігає вимкнене мислення замість зіставлення з
|
||||
Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим мислення. OpenClaw
|
||||
переписує `thinkingBudget` на підтримуваний Google `thinkingLevel` для Gemma 4.
|
||||
Якщо встановити мислення в `off`, мислення залишається вимкненим замість зіставлення з
|
||||
`MINIMAL`.
|
||||
</Tip>
|
||||
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований постачальник генерації зображень `google` за замовчуванням використовує
|
||||
Вбудований провайдер генерації зображень `google` за замовчуванням використовує
|
||||
`google/gemini-3.1-flash-image-preview`.
|
||||
|
||||
- Також підтримує `google/gemini-3-pro-image-preview`
|
||||
@ -208,7 +208,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
- Режим редагування: увімкнено, до 5 вхідних зображень
|
||||
- Керування геометрією: `size`, `aspectRatio` і `resolution`
|
||||
|
||||
Щоб використовувати Google як постачальника зображень за замовчуванням:
|
||||
Щоб використовувати Google як стандартного провайдера зображень:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -223,7 +223,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Генерація відео
|
||||
@ -231,12 +231,12 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
Вбудований Plugin `google` також реєструє генерацію відео через спільний
|
||||
інструмент `video_generate`.
|
||||
|
||||
- Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview`
|
||||
- Режими: текст-у-відео, зображення-у-відео та потоки посилання на одне відео
|
||||
- Стандартна відеомодель: `google/veo-3.1-fast-generate-preview`
|
||||
- Режими: текст-у-відео, зображення-у-відео та потоки з посиланням на одне відео
|
||||
- Підтримує `aspectRatio`, `resolution` і `audio`
|
||||
- Поточне обмеження тривалості: **від 4 до 8 секунд**
|
||||
|
||||
Щоб використовувати Google як постачальника відео за замовчуванням:
|
||||
Щоб використовувати Google як стандартного провайдера відео:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -251,7 +251,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Генерація музики
|
||||
@ -259,14 +259,14 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
Вбудований Plugin `google` також реєструє генерацію музики через спільний
|
||||
інструмент `music_generate`.
|
||||
|
||||
- Модель музики за замовчуванням: `google/lyria-3-clip-preview`
|
||||
- Стандартна музична модель: `google/lyria-3-clip-preview`
|
||||
- Також підтримує `google/lyria-3-pro-preview`
|
||||
- Керування підказкою: `lyrics` і `instrumental`
|
||||
- Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview`
|
||||
- Керування prompt: `lyrics` і `instrumental`
|
||||
- Формат виводу: `mp3` за замовчуванням, а також `wav` на `google/lyria-3-pro-preview`
|
||||
- Вхідні посилання: до 10 зображень
|
||||
- Запуски з підтримкою сеансів від’єднуються через спільний потік завдання/статусу, зокрема `action: "status"`
|
||||
- Запуски на основі сесії від’єднуються через спільний потік завдань/статусу, зокрема `action: "status"`
|
||||
|
||||
Щоб використовувати Google як постачальника музики за замовчуванням:
|
||||
Щоб використовувати Google як стандартного провайдера музики:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -281,20 +281,20 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
|
||||
Див. [Генерація музики](/uk/tools/music-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Перетворення тексту на мовлення
|
||||
|
||||
Вбудований постачальник мовлення `google` використовує шлях TTS Gemini API з
|
||||
Вбудований мовленнєвий провайдер `google` використовує шлях TTS Gemini API з
|
||||
`gemini-3.1-flash-tts-preview`.
|
||||
|
||||
- Голос за замовчуванням: `Kore`
|
||||
- Стандартний голос: `Kore`
|
||||
- Автентифікація: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY`
|
||||
- Вивід: WAV для звичайних вкладень TTS, Opus для цілей голосових нотаток, PCM для Talk/телефонії
|
||||
- Вивід голосової нотатки: Google PCM обгортається як WAV і транскодується в Opus 48 кГц за допомогою `ffmpeg`
|
||||
- Вивід голосових нотаток: Google PCM обгортається як WAV і транскодується у 48 кГц Opus за допомогою `ffmpeg`
|
||||
|
||||
Щоб використовувати Google як постачальника TTS за замовчуванням:
|
||||
Щоб використовувати Google як стандартного провайдера TTS:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -314,13 +314,13 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
|
||||
}
|
||||
```
|
||||
|
||||
TTS Gemini API використовує підказки природною мовою для керування стилем. Установіть
|
||||
`audioProfile`, щоб додати багаторазову стильову підказку перед озвучуваним текстом. Установіть
|
||||
`speakerName`, коли текст підказки посилається на названого мовця.
|
||||
TTS Gemini API використовує prompt природною мовою для керування стилем. Задайте
|
||||
`audioProfile`, щоб додати багаторазовий prompt стилю перед озвучуваним текстом. Задайте
|
||||
`speakerName`, коли текст prompt посилається на іменованого мовця.
|
||||
|
||||
TTS Gemini API також приймає виразні аудіотеги у квадратних дужках у тексті,
|
||||
наприклад `[whispers]` або `[laughs]`. Щоб теги не з’являлися у видимій відповіді чату,
|
||||
але надсилалися в TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
|
||||
наприклад `[whispers]` або `[laughs]`. Щоб не показувати теги у видимій відповіді чату,
|
||||
але надсилати їх у TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
|
||||
|
||||
```text
|
||||
Here is the clean reply text.
|
||||
@ -329,29 +329,31 @@ Here is the clean reply text.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Ключ API Google Cloud Console, обмежений Gemini API, чинний для цього
|
||||
постачальника. Це не окремий шлях Cloud Text-to-Speech API.
|
||||
API-ключ Google Cloud Console, обмежений Gemini API, є дійсним для цього
|
||||
провайдера. Це не окремий шлях Cloud Text-to-Speech API.
|
||||
</Note>
|
||||
|
||||
## Голос у реальному часі
|
||||
|
||||
Вбудований Plugin `google` реєструє постачальника голосу в реальному часі на основі
|
||||
Gemini Live API для серверних аудіомостів, як-от Voice Call і Google Meet.
|
||||
Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на основі
|
||||
Gemini Live API для бекендних аудіомостів, таких як Voice Call і Google Meet.
|
||||
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Голос | `...google.voice` | `Kore` |
|
||||
| Температура | `...google.temperature` | (не задано) |
|
||||
| Чутливість початку VAD | `...google.startSensitivity` | (не задано) |
|
||||
| Чутливість завершення VAD | `...google.endSensitivity` | (не задано) |
|
||||
| Тривалість тиші | `...google.silenceDurationMs` | (не задано) |
|
||||
| Обробка активності | `...google.activityHandling` | Типове значення Google, `start-of-activity-interrupts` |
|
||||
| Охоплення ходу | `...google.turnCoverage` | Типове значення Google, `only-activity` |
|
||||
| Вимкнути автоматичний VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Ключ API | `...google.apiKey` | Резервно використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| Налаштування | Шлях конфігурації | За замовчуванням |
|
||||
| ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Голос | `...google.voice` | `Kore` |
|
||||
| Температура | `...google.temperature` | (не задано) |
|
||||
| Чутливість початку VAD | `...google.startSensitivity` | (не задано) |
|
||||
| Чутливість завершення VAD | `...google.endSensitivity` | (не задано) |
|
||||
| Тривалість тиші | `...google.silenceDurationMs` | (не задано) |
|
||||
| Обробка активності | `...google.activityHandling` | типове значення Google, `start-of-activity-interrupts` |
|
||||
| Охоплення ходу | `...google.turnCoverage` | типове значення Google, `only-activity` |
|
||||
| Вимкнути автоматичний VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Відновлення сесії | `...google.sessionResumption` | `true` |
|
||||
| Стиснення контексту | `...google.contextWindowCompression` | `true` |
|
||||
| Ключ API | `...google.apiKey` | Повертається до `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
|
||||
Приклад конфігурації Voice Call у реальному часі:
|
||||
Приклад конфігурації Voice Call у режимі realtime:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -380,37 +382,37 @@ Gemini Live API для серверних аудіомостів, як-от Voic
|
||||
```
|
||||
|
||||
<Note>
|
||||
Google Live API використовує двонапрямний аудіопотік і виклики функцій через WebSocket.
|
||||
OpenClaw адаптує аудіо мосту телефонії/Meet до потоку PCM Live API Gemini та
|
||||
зберігає виклики інструментів у спільному контракті голосу в реальному часі. Залиште `temperature`
|
||||
незаданим, якщо вам не потрібні зміни семплінгу; OpenClaw пропускає недодатні значення,
|
||||
Google Live API використовує двонапрямне аудіо й виклики функцій через WebSocket.
|
||||
OpenClaw адаптує аудіо телекомунікаційного/Meet bridge до PCM-потоку Gemini Live API і
|
||||
залишає виклики інструментів у спільному контракті realtime voice. Залишайте `temperature`
|
||||
незаданою, якщо вам не потрібні зміни семплінгу; OpenClaw пропускає недодатні значення,
|
||||
оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`.
|
||||
Транскрипцію Gemini API увімкнено без `languageCodes`; поточний Google
|
||||
SDK відхиляє підказки кодів мов на цьому шляху API.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk підтримує браузерні сеанси Google Live з обмеженими одноразовими
|
||||
токенами. Backend-only постачальники голосу в реальному часі також можуть працювати через загальний
|
||||
транспорт ретрансляції Gateway, який зберігає облікові дані постачальника на Gateway.
|
||||
Control UI Talk підтримує браузерні сесії Google Live з обмеженими одноразовими
|
||||
токенами. Провайдери realtime voice лише для бекенду також можуть працювати через загальний
|
||||
транспорт ретрансляції Gateway, який зберігає облікові дані провайдера на Gateway.
|
||||
</Note>
|
||||
|
||||
Для live-перевірки супровідником запустіть
|
||||
Для live-перевірки мейнтейнером виконайте
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
|
||||
Гілка Google випускає токен Live API тієї самої обмеженої форми, яку використовує Control
|
||||
UI Talk, відкриває браузерну кінцеву точку WebSocket, надсилає початкове корисне навантаження налаштування
|
||||
та очікує `setupComplete`.
|
||||
Гілка Google створює ту саму форму обмеженого токена Live API, яку використовує Control
|
||||
UI Talk, відкриває браузерний кінцевий пункт WebSocket, надсилає початкове корисне навантаження налаштування
|
||||
і чекає на `setupComplete`.
|
||||
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Direct Gemini cache reuse">
|
||||
<Accordion title="Пряме повторне використання кешу Gemini">
|
||||
Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw
|
||||
передає налаштований дескриптор `cachedContent` до запитів Gemini.
|
||||
|
||||
- Налаштовуйте параметри для окремої моделі або глобально за допомогою
|
||||
`cachedContent` чи застарілого `cached_content`
|
||||
- Якщо наявні обидва, перевагу має `cachedContent`
|
||||
`cachedContent` або застарілого `cached_content`
|
||||
- Якщо присутні обидва, перемагає `cachedContent`
|
||||
- Приклад значення: `cachedContents/prebuilt-context`
|
||||
- Використання cache-hit Gemini нормалізується в OpenClaw `cacheRead` з
|
||||
upstream `cachedContentTokenCount`
|
||||
@ -433,19 +435,19 @@ UI Talk, відкриває браузерну кінцеву точку WebSock
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gemini CLI JSON usage notes">
|
||||
Під час використання OAuth-постачальника `google-gemini-cli` OpenClaw нормалізує
|
||||
<Accordion title="Примітки щодо використання JSON у Gemini CLI">
|
||||
Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує
|
||||
JSON-вивід CLI так:
|
||||
|
||||
- Текст відповіді береться з поля CLI JSON `response`.
|
||||
- Використання резервно береться зі `stats`, коли CLI залишає `usage` порожнім.
|
||||
- Дані про використання повертаються до `stats`, коли CLI залишає `usage` порожнім.
|
||||
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутнє, OpenClaw виводить вхідні токени з
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Environment and daemon setup">
|
||||
<Accordion title="Налаштування середовища й демона">
|
||||
Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
|
||||
доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через
|
||||
`env.shellEnv`).
|
||||
@ -455,16 +457,16 @@ UI Talk, відкриває браузерну кінцеву точку WebSock
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Model selection" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір постачальників, посилань на моделі та поведінки відмовостійкого перемикання.
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір провайдерів, посилань на моделі та поведінки failover.
|
||||
</Card>
|
||||
<Card title="Image generation" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри інструмента зображень і вибір постачальника.
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри інструмента зображень і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Video generation" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри інструмента відео та вибір постачальника.
|
||||
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри інструмента відео і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Music generation" href="/uk/tools/music-generation" icon="music">
|
||||
Спільні параметри інструмента музики та вибір постачальника.
|
||||
<Card title="Генерація музики" href="/uk/tools/music-generation" icon="music">
|
||||
Спільні параметри інструмента музики і вибір провайдера.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user