chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3523b00062
commit
034f52b427
@ -1,101 +1,101 @@
|
||||
---
|
||||
read_when:
|
||||
- Зміна виводу або форматів журналювання
|
||||
- Налагодження виводу CLI або gateway
|
||||
summary: Поверхні логування, файлові журнали, стилі журналів WS і форматування консолі
|
||||
- Зміна виводу або форматів логування
|
||||
- Налагодження виводу CLI або Gateway
|
||||
summary: Інтерфейси журналювання, файлові журнали, стилі журналів WS і форматування консолі
|
||||
title: Журналювання Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T23:13:06Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-01T05:53:12Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9ce9c78201d2e26760282b08eacb17826b1eac84e80b99d3a9d5cbff4078b5b3
|
||||
source_hash: f843812a41c25f9ca1884543ad3a5663c8e0bc327027cbd2b58ea6557c466aa9
|
||||
source_path: gateway/logging.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Журналювання
|
||||
|
||||
Огляд для користувачів (CLI + Control UI + конфігурація) див. у [/logging](/uk/logging).
|
||||
Огляд для користувачів (CLI + інтерфейс керування + конфігурація) див. у [/logging](/uk/logging).
|
||||
|
||||
OpenClaw має дві «поверхні» журналювання:
|
||||
OpenClaw має дві “поверхні” журналів:
|
||||
|
||||
- **Вивід у консоль** (те, що ви бачите в терміналі / Debug UI).
|
||||
- **Файлові журнали** (рядки JSON), які записує реєстратор Gateway.
|
||||
- **Вивід у консоль** (те, що ви бачите в терміналі / інтерфейсі налагодження).
|
||||
- **Файлові журнали** (рядки JSON), які записує логер Gateway.
|
||||
|
||||
## Файловий реєстратор
|
||||
## Файловий логер
|
||||
|
||||
- Типовий файл журналу з ротацією розміщується в `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log`
|
||||
- Дата використовує локальний часовий пояс хоста gateway.
|
||||
- Активні файли журналів ротуються на `logging.maxFileBytes` (типово: 100 MB), із збереженням
|
||||
до п’яти нумерованих архівів і продовженням запису в новий активний файл.
|
||||
- Шлях до файла журналу й рівень можна налаштувати через `~/.openclaw/openclaw.json`:
|
||||
- Типовий ротаційний файл журналу розташований у `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log`
|
||||
- Дата використовує локальний часовий пояс хоста Gateway.
|
||||
- Активні файли журналу ротуються при `logging.maxFileBytes` (типово: 100 МБ), зберігаючи
|
||||
до п’яти нумерованих архівів і продовжуючи запис у новий активний файл.
|
||||
- Шлях до файла журналу та рівень можна налаштувати через `~/.openclaw/openclaw.json`:
|
||||
- `logging.file`
|
||||
- `logging.level`
|
||||
|
||||
Формат файла — один об’єкт JSON на рядок.
|
||||
|
||||
Вкладка Logs у Control UI відстежує цей файл через gateway (`logs.tail`).
|
||||
Вкладка журналів інтерфейсу керування стежить за цим файлом через Gateway (`logs.tail`).
|
||||
CLI може робити те саме:
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
**Докладний режим і рівні журналювання**
|
||||
**Докладність проти рівнів журналювання**
|
||||
|
||||
- **Файлові журнали** керуються виключно через `logging.level`.
|
||||
- `--verbose` впливає лише на **деталізацію консолі** (і стиль журналів WS); він **не**
|
||||
підвищує рівень файлових журналів.
|
||||
- Щоб зберігати деталі лише для докладного режиму у файлових журналах, установіть `logging.level` на `debug` або
|
||||
- **Файлові журнали** керуються виключно `logging.level`.
|
||||
- `--verbose` впливає лише на **докладність консолі** (і стиль журналів WS); він **не**
|
||||
підвищує рівень файлового журналювання.
|
||||
- Щоб записувати у файлові журнали деталі, доступні лише в докладному режимі, установіть `logging.level` у `debug` або
|
||||
`trace`.
|
||||
|
||||
## Захоплення консолі
|
||||
## Перехоплення консолі
|
||||
|
||||
CLI перехоплює `console.log/info/warn/error/debug/trace` і записує їх у файлові журнали,
|
||||
водночас продовжуючи виводити їх у stdout/stderr.
|
||||
водночас продовжуючи друкувати у stdout/stderr.
|
||||
|
||||
Ви можете окремо налаштувати деталізацію консолі через:
|
||||
Докладність консолі можна налаштувати незалежно через:
|
||||
|
||||
- `logging.consoleLevel` (типово `info`)
|
||||
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
|
||||
|
||||
## Редагування чутливих даних
|
||||
## Редагування секретів
|
||||
|
||||
OpenClaw може маскувати чутливі токени до того, як вивід журналу або транскрипту залишить
|
||||
процес. Ця політика редагування для журналювання застосовується до консолі, файлових журналів, OTLP
|
||||
записів журналів і текстових приймачів транскриптів сеансів, тому відповідні значення секретів
|
||||
маскуються до того, як рядки JSONL або повідомлення записуються на диск.
|
||||
OpenClaw може маскувати чутливі токени до того, як вивід журналу або транскрипта залишить
|
||||
процес. Ця політика редагування журналів застосовується до консолі, файлового журналу, записів журналу OTLP
|
||||
і текстових приймачів транскриптів сесій, тому відповідні секретні значення
|
||||
маскуються до запису рядків JSONL або повідомлень на диск.
|
||||
|
||||
- `logging.redactSensitive`: `off` | `tools` (типово: `tools`)
|
||||
- `logging.redactPatterns`: масив рядків regex (перевизначає типові значення)
|
||||
- Використовуйте необроблені рядки regex (автоматично `gi`) або `/pattern/flags`, якщо вам потрібні власні прапорці.
|
||||
- `logging.redactPatterns`: масив рядків регулярних виразів (перевизначає типові значення)
|
||||
- Використовуйте необроблені рядки регулярних виразів (автоматично `gi`) або `/pattern/flags`, якщо потрібні власні прапорці.
|
||||
- Збіги маскуються зі збереженням перших 6 + останніх 4 символів (довжина >= 18), інакше `***`.
|
||||
- Типові значення охоплюють поширені присвоєння ключів, прапорці CLI, поля JSON, заголовки bearer, блоки PEM і популярні префікси токенів.
|
||||
- Типові значення покривають поширені присвоєння ключів, прапорці CLI, поля JSON, bearer-заголовки, блоки PEM, популярні префікси токенів і назви полів платіжних облікових даних, як-от номер картки, CVC/CVV, спільний платіжний токен і платіжні облікові дані.
|
||||
|
||||
Деякі межі безпеки завжди виконують редагування незалежно від `logging.redactSensitive`.
|
||||
Сюди входять події виклику інструментів у Control UI, вивід інструмента `sessions_history`,
|
||||
експорти діагностичної підтримки, спостереження за помилками провайдера, відображення команди схвалення exec
|
||||
і журнали протоколу Gateway WebSocket. Ці поверхні все одно можуть використовувати
|
||||
Деякі межі безпеки завжди редагують секрети незалежно від `logging.redactSensitive`.
|
||||
Сюди входять події викликів інструментів інтерфейсу керування, вивід інструмента `sessions_history`,
|
||||
експорти підтримки діагностики, спостереження помилок провайдерів, показ команди схвалення exec
|
||||
і журнали протоколу Gateway WebSocket. Ці поверхні все ще можуть використовувати
|
||||
`logging.redactPatterns` як додаткові шаблони, але `redactSensitive: "off"`
|
||||
не змушує їх виводити необроблені секрети.
|
||||
|
||||
## Журнали Gateway WebSocket
|
||||
|
||||
Gateway виводить журнали протоколу WebSocket у двох режимах:
|
||||
Gateway друкує журнали протоколу WebSocket у двох режимах:
|
||||
|
||||
- **Звичайний режим (без `--verbose`)**: виводяться лише «цікаві» результати RPC:
|
||||
- **Звичайний режим (без `--verbose`)**: друкуються лише “цікаві” результати RPC:
|
||||
- помилки (`ok=false`)
|
||||
- повільні виклики (типовий поріг: `>= 50ms`)
|
||||
- помилки розбору
|
||||
- **Докладний режим (`--verbose`)**: виводить увесь трафік запитів/відповідей WS.
|
||||
- **Докладний режим (`--verbose`)**: друкує весь трафік запитів/відповідей WS.
|
||||
|
||||
### Стиль журналів WS
|
||||
|
||||
`openclaw gateway` підтримує окреме перемикання стилю для gateway:
|
||||
`openclaw gateway` підтримує перемикач стилю для кожного Gateway:
|
||||
|
||||
- `--ws-log auto` (типово): звичайний режим оптимізований; у докладному режимі використовується компактний вивід
|
||||
- `--ws-log compact`: компактний вивід (парний запит/відповідь) у докладному режимі
|
||||
- `--ws-log full`: повний вивід для кожного кадру в докладному режимі
|
||||
- `--ws-log auto` (типово): звичайний режим оптимізований; докладний режим використовує компактний вивід
|
||||
- `--ws-log compact`: компактний вивід (парні запит/відповідь) у докладному режимі
|
||||
- `--ws-log full`: повний вивід для кожного фрейму в докладному режимі
|
||||
- `--compact`: псевдонім для `--ws-log compact`
|
||||
|
||||
Приклади:
|
||||
@ -113,22 +113,22 @@ openclaw gateway --verbose --ws-log full
|
||||
|
||||
## Форматування консолі (журналювання підсистем)
|
||||
|
||||
Форматер консолі **враховує TTY** і виводить узгоджені рядки з префіксами.
|
||||
Реєстратори підсистем зберігають вивід згрупованим і зручним для перегляду.
|
||||
Форматер консолі **враховує TTY** і друкує узгоджені рядки з префіксами.
|
||||
Логери підсистем групують вивід і роблять його зручним для перегляду.
|
||||
|
||||
Поведінка:
|
||||
|
||||
- **Префікси підсистем** у кожному рядку (наприклад, `[gateway]`, `[canvas]`, `[tailscale]`)
|
||||
- **Кольори підсистем** (сталі для кожної підсистеми) плюс кольори рівнів
|
||||
- **Кольори підсистем** (стабільні для кожної підсистеми) плюс забарвлення рівнів
|
||||
- **Колір, коли вивід є TTY або середовище схоже на розширений термінал** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), з урахуванням `NO_COLOR`
|
||||
- **Скорочені префікси підсистем**: відкидає початкові `gateway/` + `channels/`, зберігає останні 2 сегменти (наприклад, `whatsapp/outbound`)
|
||||
- **Підреєстратори за підсистемами** (автоматичний префікс + структуроване поле `{ subsystem }`)
|
||||
- **`logRaw()`** для QR/UX-виводу (без префікса, без форматування)
|
||||
- **Скорочені префікси підсистем**: відкидає початкові `gateway/` + `channels/`, залишає останні 2 сегменти (наприклад, `whatsapp/outbound`)
|
||||
- **Підлогери за підсистемами** (автоматичний префікс + структуроване поле `{ subsystem }`)
|
||||
- **`logRaw()`** для виводу QR/UX (без префікса, без форматування)
|
||||
- **Стилі консолі** (наприклад, `pretty | compact | json`)
|
||||
- **Рівень журналу консолі** окремо від рівня файлового журналу (файл зберігає повну деталізацію, коли `logging.level` установлено в `debug`/`trace`)
|
||||
- **Тіла повідомлень WhatsApp** журналюються на рівні `debug` (використовуйте `--verbose`, щоб їх бачити)
|
||||
- **Рівень журналювання консолі** окремий від рівня файлового журналювання (файл зберігає повну деталізацію, коли `logging.level` установлено в `debug`/`trace`)
|
||||
- **Тіла повідомлень WhatsApp** журналюються на рівні `debug` (використовуйте `--verbose`, щоб їх побачити)
|
||||
|
||||
Це зберігає наявні файлові журнали стабільними, водночас роблячи інтерактивний вивід зручним для перегляду.
|
||||
Це зберігає стабільність наявних файлових журналів і водночас робить інтерактивний вивід зручним для перегляду.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
@ -2,14 +2,14 @@
|
||||
read_when:
|
||||
- Вам потрібен зручний для початківців огляд журналювання OpenClaw
|
||||
- Ви хочете налаштувати рівні журналювання, формати або маскування
|
||||
- Ви усуваєте неполадки й вам потрібно швидко знайти журнали
|
||||
summary: Файлові журнали, вивід консолі, стеження за журналами через CLI та вкладка журналів в інтерфейсі керування
|
||||
- Ви усуваєте несправність і вам потрібно швидко знайти журнали
|
||||
summary: Файлові журнали, вивід консолі, відстеження CLI та вкладка «Журнали» інтерфейсу керування
|
||||
title: Журналювання
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T07:14:12Z"
|
||||
generated_at: "2026-05-01T05:53:19Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 916fb03219d571f0302560a4cb6755940575c92fff0b4eab024b9dad53f841ce
|
||||
source_hash: d41ce5b1ae30fe1ca65577abe387fc266bd281686acb10098f82b8e78dfaa357
|
||||
source_path: logging.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,9 +17,9 @@ x-i18n:
|
||||
OpenClaw має дві основні поверхні журналювання:
|
||||
|
||||
- **Файлові журнали** (рядки JSON), які записує Gateway.
|
||||
- **Вивід консолі**, що показується в терміналах і Gateway Debug UI.
|
||||
- **Консольний вивід**, що відображається в терміналах і Gateway Debug UI.
|
||||
|
||||
Вкладка **Logs** у Control UI відстежує файловий журнал Gateway. На цій сторінці пояснено, де
|
||||
Вкладка **Logs** у Control UI відстежує файловий журнал gateway. Ця сторінка пояснює, де
|
||||
зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання.
|
||||
|
||||
## Де зберігаються журнали
|
||||
@ -28,11 +28,11 @@ OpenClaw має дві основні поверхні журналювання:
|
||||
|
||||
`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
|
||||
|
||||
Дата використовує локальний часовий пояс хоста Gateway.
|
||||
Дата використовує локальний часовий пояс хоста gateway.
|
||||
|
||||
Кожен файл ротуються, коли досягає `logging.maxFileBytes` (за замовчуванням: 100 MB).
|
||||
Кожен файл ротується, коли досягає `logging.maxFileBytes` (за замовчуванням: 100 MB).
|
||||
OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом, наприклад
|
||||
`openclaw-YYYY-MM-DD.1.log`, і продовжує писати в новий активний журнал замість
|
||||
`openclaw-YYYY-MM-DD.1.log`, і продовжує писати до нового активного журналу замість
|
||||
пригнічення діагностики.
|
||||
|
||||
Це можна перевизначити в `~/.openclaw/openclaw.json`:
|
||||
@ -47,9 +47,9 @@ OpenClaw зберігає до п’яти нумерованих архівів
|
||||
|
||||
## Як читати журнали
|
||||
|
||||
### CLI: живе відстеження (рекомендовано)
|
||||
### CLI: відстеження наживо (рекомендовано)
|
||||
|
||||
Використовуйте CLI, щоб відстежувати файл журналу Gateway через RPC:
|
||||
Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC:
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
@ -57,19 +57,19 @@ openclaw logs --follow
|
||||
|
||||
Корисні поточні параметри:
|
||||
|
||||
- `--local-time`: відображати часові позначки у вашому локальному часовому поясі
|
||||
- `--url <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці RPC Gateway
|
||||
- `--local-time`: відображати часові мітки у вашому локальному часовому поясі
|
||||
- `--url <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці Gateway RPC
|
||||
- `--expect-final`: прапорець очікування фінальної відповіді RPC на базі агента (приймається тут через спільний клієнтський шар)
|
||||
|
||||
Режими виводу:
|
||||
|
||||
- **TTY-сеанси**: красиві, кольорові, структуровані рядки журналу.
|
||||
- **Не-TTY-сеанси**: простий текст.
|
||||
- `--json`: JSON із розділенням за рядками (одна подія журналу на рядок).
|
||||
- `--plain`: примусово використовувати простий текст у TTY-сеансах.
|
||||
- `--no-color`: вимкнути кольори ANSI.
|
||||
- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу.
|
||||
- **Не-TTY-сеанси**: звичайний текст.
|
||||
- `--json`: JSON з розділенням за рядками (одна подія журналу на рядок).
|
||||
- `--plain`: примусово використовувати звичайний текст у TTY-сеансах.
|
||||
- `--no-color`: вимкнути ANSI-кольори.
|
||||
|
||||
Коли ви передаєте явний `--url`, CLI автоматично не застосовує конфігураційні або
|
||||
Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігураційні або
|
||||
середовищні облікові дані; додайте `--token` самостійно, якщо цільовий Gateway
|
||||
вимагає автентифікації.
|
||||
|
||||
@ -77,15 +77,15 @@ openclaw logs --follow
|
||||
|
||||
- `meta`: метадані потоку (файл, курсор, розмір)
|
||||
- `log`: розібраний запис журналу
|
||||
- `notice`: підказки про обрізання / ротацію
|
||||
- `notice`: підказки щодо обрізання / ротації
|
||||
- `raw`: нерозібраний рядок журналу
|
||||
|
||||
Якщо неявний Gateway через local loopback запитує сполучення, закривається під час підключення
|
||||
або час очікування минає до відповіді `logs.tail`, `openclaw logs` автоматично
|
||||
переходить до налаштованого файлового журналу Gateway. Явні цілі `--url` не використовують
|
||||
цей резервний варіант.
|
||||
або вичерпує час очікування до відповіді `logs.tail`, `openclaw logs` автоматично
|
||||
повертається до налаштованого файлового журналу Gateway. Явні цілі `--url` не використовують
|
||||
цей резервний шлях.
|
||||
|
||||
Якщо Gateway недоступний, CLI виводить коротку підказку виконати:
|
||||
Якщо Gateway недоступний, CLI друкує коротку підказку виконати:
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
@ -109,31 +109,31 @@ openclaw channels logs --channel whatsapp
|
||||
### Файлові журнали (JSONL)
|
||||
|
||||
Кожен рядок у файлі журналу є об’єктом JSON. CLI і Control UI розбирають ці
|
||||
записи, щоб відображати структурований вивід (час, рівень, підсистему, повідомлення).
|
||||
записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення).
|
||||
|
||||
Записи JSONL файлового журналу також містять придатні для машинної фільтрації поля верхнього рівня, коли
|
||||
Записи JSONL файлового журналу також містять машинно-фільтровані поля верхнього рівня, коли
|
||||
вони доступні:
|
||||
|
||||
- `hostname`: ім’я хоста Gateway.
|
||||
- `message`: сплющений текст повідомлення журналу для повнотекстового пошуку.
|
||||
- `agent_id`: id активного агента, коли виклик журналу містить контекст агента.
|
||||
- `session_id`: id/ключ активного сеансу, коли виклик журналу містить контекст сеансу.
|
||||
- `channel`: активний канал, коли виклик журналу містить контекст каналу.
|
||||
- `hostname`: ім’я хоста gateway.
|
||||
- `message`: сплощений текст повідомлення журналу для повнотекстового пошуку.
|
||||
- `agent_id`: ідентифікатор активного агента, коли виклик журналювання має контекст агента.
|
||||
- `session_id`: ідентифікатор/ключ активного сеансу, коли виклик журналювання має контекст сеансу.
|
||||
- `channel`: активний канал, коли виклик журналювання має контекст каналу.
|
||||
|
||||
OpenClaw зберігає початкові структуровані аргументи журналу поруч із цими полями,
|
||||
щоб наявні парсери, які читають нумеровані ключі аргументів tslog, продовжували працювати.
|
||||
|
||||
### Вивід консолі
|
||||
### Консольний вивід
|
||||
|
||||
Консольні журнали **враховують TTY** і форматуються для читабельності:
|
||||
Консольні журнали **враховують TTY** і форматуються для зручності читання:
|
||||
|
||||
- Префікси підсистем (наприклад, `gateway/channels/whatsapp`)
|
||||
- Кольорування рівнів (info/warn/error)
|
||||
- Необов’язковий компактний режим або режим JSON
|
||||
|
||||
Форматування консолі керується `logging.consoleStyle`.
|
||||
Консольне форматування керується `logging.consoleStyle`.
|
||||
|
||||
### Журнали WebSocket Gateway
|
||||
### Журнали Gateway WebSocket
|
||||
|
||||
`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку:
|
||||
|
||||
@ -172,90 +172,94 @@ openclaw gateway --verbose --ws-log full
|
||||
- `logging.level`: рівень **файлових журналів** (JSONL).
|
||||
- `logging.consoleLevel`: рівень докладності **консолі**.
|
||||
|
||||
Можна перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над конфігураційним файлом, тож можна підвищити докладність для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
Обидва можна перевизначити через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тож можна підвищити докладність для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
|
||||
`--verbose` впливає лише на вивід консолі та докладність журналу WS; він не змінює
|
||||
`--verbose` впливає лише на консольний вивід і докладність журналів WS; він не змінює
|
||||
рівні файлового журналювання.
|
||||
|
||||
### Кореляція трасування
|
||||
|
||||
Файлові журнали мають формат JSONL. Коли виклик журналу містить дійсний контекст діагностичного трасування,
|
||||
Файлові журнали мають формат JSONL. Коли виклик журналювання має дійсний контекст діагностичного трасування,
|
||||
OpenClaw записує поля трасування як ключі JSON верхнього рівня (`traceId`, `spanId`,
|
||||
`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли пов’язати рядок
|
||||
зі span OTEL і поширенням `traceparent` провайдера.
|
||||
`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли співвідносити рядок
|
||||
зі спанами OTEL і поширенням `traceparent` провайдера.
|
||||
|
||||
HTTP-запити Gateway і кадри WebSocket Gateway встановлюють внутрішню область трасування
|
||||
запиту. Журнали та діагностичні події, створені всередині цієї асинхронної області, успадковують
|
||||
трасування запиту, коли не передають явний контекст трасування. Трасування запуску агента та
|
||||
виклику моделі стають дочірніми від активного трасування запиту, тому локальні журнали,
|
||||
діагностичні знімки, span OTEL і довірені заголовки `traceparent` провайдера можна
|
||||
об’єднати за `traceId` без журналювання сирого вмісту запиту або моделі.
|
||||
HTTP-запити Gateway і кадри Gateway WebSocket встановлюють внутрішню область трасування
|
||||
запиту. Журнали й діагностичні події, емітовані в цій асинхронній області, успадковують
|
||||
трасування запиту, коли вони не передають явний контекст трасування. Трасування запуску агента й
|
||||
викликів моделі стають дочірніми до активного трасування запиту, тому локальні журнали,
|
||||
діагностичні знімки, спани OTEL і довірені заголовки `traceparent` провайдера можна
|
||||
об’єднувати за `traceId` без журналювання сирого вмісту запиту або моделі.
|
||||
|
||||
### Розмір і час виклику моделі
|
||||
|
||||
Діагностика викликів моделі записує обмежені вимірювання запиту/відповіді без
|
||||
захоплення сирого вмісту prompt або відповіді:
|
||||
захоплення сирого вмісту промпта або відповіді:
|
||||
|
||||
- `requestPayloadBytes`: розмір у байтах UTF-8 фінального payload запиту моделі
|
||||
- `requestPayloadBytes`: розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі
|
||||
- `responseStreamBytes`: розмір у байтах UTF-8 потокових подій відповіді моделі
|
||||
- `timeToFirstByteMs`: час, що минув до першої потокової події відповіді
|
||||
- `durationMs`: загальна тривалість виклику моделі
|
||||
|
||||
Ці поля доступні діагностичним знімкам, хукам Plugin для викликів моделі та
|
||||
span/метрикам викликів моделі OTEL, коли експорт діагностики ввімкнено.
|
||||
Ці поля доступні для діагностичних знімків, хуків Plugin для викликів моделі та
|
||||
спанів/метрик викликів моделі OTEL, коли експорт діагностики ввімкнено.
|
||||
|
||||
### Стилі консолі
|
||||
|
||||
`logging.consoleStyle`:
|
||||
|
||||
- `pretty`: зручний для людини, кольоровий, із часовими позначками.
|
||||
- `pretty`: зручний для людини, кольоровий, з часовими мітками.
|
||||
- `compact`: щільніший вивід (найкраще для довгих сеансів).
|
||||
- `json`: JSON на рядок (для обробників журналів).
|
||||
|
||||
### Редагування секретів
|
||||
### Редакція
|
||||
|
||||
OpenClaw може редагувати чутливі токени до того, як вони потраплять у вивід консолі, файлові журнали,
|
||||
записи журналів OTLP, збережений текст транскрипту сеансу або payload подій інструментів
|
||||
Control UI (аргументи запуску інструменту, часткові/фінальні payload результатів, похідний
|
||||
вивід exec і підсумки patch):
|
||||
OpenClaw може редагувати чутливі токени до того, як вони потраплять у консольний вивід, файлові журнали,
|
||||
записи журналу OTLP, збережений текст стенограми сеансу або корисні навантаження подій інструментів
|
||||
Control UI (аргументи запуску інструмента, часткові/фінальні корисні навантаження результату, похідний
|
||||
вивід exec і зведення патчів):
|
||||
|
||||
- `logging.redactSensitive`: `off` | `tools` (за замовчуванням: `tools`)
|
||||
- `logging.redactPatterns`: список regex-рядків для перевизначення стандартного набору. Користувацькі шаблони застосовуються поверх вбудованих стандартних шаблонів для payload інструментів Control UI, тому додавання шаблону ніколи не послаблює редагування значень, які вже виявляються стандартними шаблонами.
|
||||
- `logging.redactPatterns`: список рядків regex для перевизначення стандартного набору. Власні шаблони застосовуються поверх вбудованих стандартних значень для корисних навантажень інструментів Control UI, тож додавання шаблону ніколи не послаблює редакцію значень, які вже знаходять стандартні правила.
|
||||
|
||||
Файлові журнали та транскрипти сеансів залишаються JSONL, але відповідні секретні значення
|
||||
маскуються до запису рядка або повідомлення на диск. Редагування виконується за принципом найкращого зусилля:
|
||||
воно застосовується до текстового вмісту повідомлень і рядків журналів, а не до кожного
|
||||
ідентифікатора або поля бінарного payload.
|
||||
Файлові журнали й стенограми сеансів залишаються JSONL, але відповідні секретні значення
|
||||
маскуються до запису рядка або повідомлення на диск. Редакція виконується за принципом найкращих зусиль:
|
||||
вона застосовується до текстового вмісту повідомлень і рядків журналу, а не до кожного
|
||||
ідентифікатора чи поля бінарного корисного навантаження.
|
||||
|
||||
`logging.redactSensitive: "off"` вимикає лише цю загальну політику журналів/транскриптів.
|
||||
OpenClaw усе одно редагує payload меж безпеки, які можуть показуватися UI
|
||||
клієнтам, пакетам підтримки, спостерігачам діагностики, запитам схвалення або
|
||||
інструментам агента. Приклади включають події виклику інструментів Control UI, вивід `sessions_history`,
|
||||
експорти діагностики для підтримки, спостереження помилок провайдера, показ команди для схвалення exec
|
||||
і журнали протоколу WebSocket Gateway. Користувацькі `logging.redactPatterns`
|
||||
можуть і далі додавати шаблони, специфічні для проєкту, на цих поверхнях.
|
||||
Вбудовані стандартні правила охоплюють поширені облікові дані API й імена полів платіжних облікових даних,
|
||||
такі як номер картки, CVC/CVV, спільний платіжний токен і платіжні облікові дані,
|
||||
коли вони з’являються як поля JSON, параметри URL, прапорці CLI або присвоєння.
|
||||
|
||||
## Діагностика та OpenTelemetry
|
||||
`logging.redactSensitive: "off"` вимикає лише цю загальну політику журналів/стенограм.
|
||||
OpenClaw усе одно редагує корисні навантаження меж безпеки, які можуть показуватися UI
|
||||
клієнтам, пакетам підтримки, спостерігачам діагностики, запитам схвалення або інструментам
|
||||
агента. Приклади: події викликів інструментів Control UI, вивід `sessions_history`,
|
||||
експорти підтримки діагностики, спостереження помилок провайдера, відображення команди
|
||||
схвалення exec і журнали протоколу Gateway WebSocket. Власні `logging.redactPatterns`
|
||||
усе ще можуть додавати проєктно-специфічні шаблони на цих поверхнях.
|
||||
|
||||
Діагностика — це структуровані, машинозчитувані події для запусків моделі та
|
||||
телеметрії потоку повідомлень (webhook-и, постановка в чергу, стан сеансу). Вони **не**
|
||||
замінюють журнали — вони живлять метрики, трасування та експортери. Події створюються
|
||||
в процесі незалежно від того, експортуєте ви їх чи ні.
|
||||
## Діагностика й OpenTelemetry
|
||||
|
||||
Діагностика — це структуровані, машинно-читані події для запусків моделі й
|
||||
телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не**
|
||||
замінюють журнали — вони живлять метрики, трасування й експортери. Події емітуються
|
||||
всередині процесу незалежно від того, експортуєте ви їх чи ні.
|
||||
|
||||
Дві суміжні поверхні:
|
||||
|
||||
- **Експорт OpenTelemetry** — надсилання метрик, трасувань і журналів через OTLP/HTTP до
|
||||
будь-якого сумісного з OpenTelemetry колектора або бекенду (Grafana, Datadog,
|
||||
будь-якого колектора або бекенду, сумісного з OpenTelemetry (Grafana, Datadog,
|
||||
Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів,
|
||||
назви метрик/span, змінні середовища та модель приватності розміщені на окремій сторінці:
|
||||
назви метрик/спанів, змінні середовища й модель приватності розміщені на окремій сторінці:
|
||||
[Експорт OpenTelemetry](/uk/gateway/opentelemetry).
|
||||
- **Прапорці діагностики** — цільові прапорці debug-журналів, які спрямовують додаткові журнали до
|
||||
- **Прапорці діагностики** — цільові прапорці журналів налагодження, які спрямовують додаткові журнали до
|
||||
`logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру
|
||||
і підтримують символи узагальнення (`telegram.*`, `*`). Налаштовуйте в `diagnostics.flags`
|
||||
й підтримують символи підстановки (`telegram.*`, `*`). Налаштовуйте в `diagnostics.flags`
|
||||
або через перевизначення змінної середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник:
|
||||
[Прапорці діагностики](/uk/diagnostics/flags).
|
||||
|
||||
Щоб увімкнути діагностичні події для plugin-ів або користувацьких приймачів без експорту OTLP:
|
||||
Щоб увімкнути діагностичні події для plugins або власних приймачів без експорту OTLP:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,7 +278,7 @@ OpenClaw усе одно редагує payload меж безпеки, які м
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель приватності
|
||||
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-журналів
|
||||
- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналу WS, префікси підсистем і захоплення консолі
|
||||
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повна довідка полів `diagnostics.*`
|
||||
- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/спанів, модель приватності
|
||||
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналів налагодження
|
||||
- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий виклик з OpenClaw
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
|
||||
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії
|
||||
- Вам потрібен голос у реальному часі або потокова транскрипція в телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з опційним голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T05:39:49Z"
|
||||
generated_at: "2026-05-01T05:53:21Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 08690f9f27de8a3d4d2c6056cd08edcc42f60f0592272a464c07cb1dc7fee26e
|
||||
source_hash: 9ec854553cbba692ac9b3e929b107937332949c62aabe7192cdc9dcaa5537d74
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Голосові виклики для OpenClaw через плагін. Підтримує вихідні сповіщення,
|
||||
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками allowlist.
|
||||
Дзвінки голосом для OpenClaw через Plugin. Підтримує вихідні сповіщення,
|
||||
багатоетапні розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні дзвінки з політиками списку дозволених.
|
||||
|
||||
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Плагін Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте плагін на машині, де запущено
|
||||
Plugin дзвінків голосом працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть плагін">
|
||||
<Step title="Install the plugin">
|
||||
<Tabs>
|
||||
<Tab title="З npm">
|
||||
<Tab title="From npm">
|
||||
```bash
|
||||
openclaw plugins install @openclaw/voice-call
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="З локальної папки (розробка)">
|
||||
<Tab title="From a local folder (dev)">
|
||||
```bash
|
||||
PLUGIN_SRC=./path/to/local/voice-call-plugin
|
||||
openclaw plugins install "$PLUGIN_SRC"
|
||||
@ -48,38 +48,38 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, є застарілим, ця версія пакета
|
||||
Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку OpenClaw
|
||||
або шлях до локальної папки, доки не буде опубліковано новіший пакет npm.
|
||||
або шлях до локальної папки, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
Після цього перезапустіть Gateway, щоб плагін завантажився.
|
||||
Після цього перезапустіть Gateway, щоб Plugin завантажився.
|
||||
|
||||
</Step>
|
||||
<Step title="Налаштуйте провайдера та webhook">
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
|
||||
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і загальнодоступна
|
||||
URL-адреса webhook.
|
||||
<Step title="Configure provider and webhook">
|
||||
Установіть конфігурацію в `plugins.entries.voice-call.config` (див.
|
||||
[Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і публічно
|
||||
доступна URL-адреса Webhook.
|
||||
</Step>
|
||||
<Step title="Перевірте налаштування">
|
||||
<Step title="Verify setup">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
Типовий вивід зручно читати в журналах чатів і терміналах. Він перевіряє
|
||||
ввімкнення плагіна, облікові дані провайдера, доступність webhook і те, що
|
||||
активний лише один аудіорежим (`streaming` або `realtime`). Для скриптів використовуйте
|
||||
`--json`.
|
||||
Вивід за замовчуванням зручно читати в журналах чату й терміналах. Він перевіряє,
|
||||
чи ввімкнено Plugin, облікові дані провайдера, доступність Webhook і те, що
|
||||
активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
`--json` для скриптів.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke-тест">
|
||||
<Step title="Smoke test">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Обидві команди за замовчуванням виконуються як пробні запуски. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний дзвінок зі сповіщенням:
|
||||
Обидва варіанти за замовчуванням є пробними запусками. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний дзвінок-сповіщення:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -89,21 +89,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу webhook**.
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса Webhook**.
|
||||
Якщо `publicUrl`, URL-адреса тунелю, URL-адреса Tailscale або резервний варіант serve
|
||||
визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати webhook від оператора.
|
||||
визначаються як loopback або приватний мережевий простір, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не може отримувати Webhook від оператора.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
|
||||
пропускає запуск runtime. Команди, RPC-виклики й інструменти агента все одно
|
||||
під час запуску Gateway у журнал записується попередження про неповне налаштування з відсутніми ключами, і
|
||||
запуск runtime пропускається. Команди, RPC-виклики й інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
|
||||
<Note>
|
||||
Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Облікові дані voice-call підтримують SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -164,24 +164,24 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Нотатки щодо доступності провайдера та безпеки">
|
||||
- Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси webhook.
|
||||
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не має значення true.
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- 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` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безплатного тарифу Ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Продакшн: надавайте перевагу стабільному домену або funnel Tailscale.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ліміти потокових з’єднань">
|
||||
<Accordion title="Streaming connection caps">
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів перед стартом.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети перед стартом для однієї вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувані + активні).
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети до старту для кожної вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Міграції застарілої конфігурації">
|
||||
<Accordion title="Legacy config migrations">
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Резервний runtime поки що все ще приймає старі ключі voice-call, але
|
||||
@ -201,34 +201,34 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає повнодуплексного провайдера голосу в реальному часі для живого аудіо виклику.
|
||||
Він відокремлений від `streaming`, який лише пересилає аудіо
|
||||
`realtime` вибирає повнодуплексного голосового провайдера реального часу для аудіо
|
||||
дзвінка наживо. Це окремо від `streaming`, який лише пересилає аудіо
|
||||
провайдерам транскрипції в реальному часі.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
|
||||
аудіорежим для кожного виклику.
|
||||
аудіорежим для кожного дзвінка.
|
||||
</Warning>
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `realtime.enabled` підтримується для Twilio Media Streams.
|
||||
- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
|
||||
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, міститься в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням відкриває спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного провайдера голосу в реальному часі, Voice Call записує попередження й пропускає медіа реального часу замість того, щоб зупиняти весь плагін з помилкою.
|
||||
- Ключі сесії consult повторно використовують наявну голосову сесію, коли вона доступна, а потім переходять до номера телефону абонента/одержувача, щоб подальші виклики consult зберігали контекст під час дзвінка.
|
||||
- `realtime.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу.
|
||||
- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми провайдерськими Plugin.
|
||||
- Необроблена конфігурація, якою володіє провайдер, розміщується в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного голосового провайдера реального часу, Voice Call записує попередження в журнал і пропускає медіа реального часу замість того, щоб зупиняти весь Plugin з помилкою.
|
||||
- Ключі сеансу консультації повторно використовують наявний голосовий сеанс, коли він доступний, а потім повертаються до номера телефону абонента/отримувача, щоб подальші 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` усе одно передаються провайдеру реального часу. |
|
||||
|
||||
### Приклади провайдерів реального часу
|
||||
|
||||
@ -292,20 +292,20 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai), щоб дізнатися про параметри голосу в реальному часі,
|
||||
специфічні для провайдера.
|
||||
[провайдера OpenAI](/uk/providers/openai) для параметрів голосу в реальному часі,
|
||||
специфічних для провайдера.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для аудіо дзвінка наживо.
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `streaming.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, міститься в `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`), зареєстровані їхніми провайдерськими Plugin.
|
||||
- Необроблена конфігурація, якою володіє провайдер, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб зупиняти весь Plugin з помилкою.
|
||||
|
||||
### Приклади провайдерів streaming
|
||||
|
||||
@ -344,7 +344,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
|
||||
@ -378,8 +378,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
## TTS для викликів
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації plugin з
|
||||
**тією самою структурою** — вона глибоко об'єднується з `messages.tts`.
|
||||
мовлення під час викликів. Її можна перевизначити в конфігурації Plugin із
|
||||
**такою самою формою** — вона глибоко об’єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -396,22 +396,22 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонний звук потребує PCM;
|
||||
поточний транспорт Microsoft не надає телефонний вихід PCM.
|
||||
**Мовлення Microsoft ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM;
|
||||
поточний транспорт Microsoft не надає телефонний PCM-вивід.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли ввімкнено медіапотокове передавання Twilio; інакше виклики повертаються до нативних голосів провайдера.
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли потокове передавання медіа Twilio увімкнене; інакше виклики повертаються до голосів, нативних для провайдера.
|
||||
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо телефонний TTS у цьому стані недоступний, запит відтворення завершується помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
|
||||
- Коли Twilio barge-in або завершення потоку очищає чергу TTS, запити відтворення в черзі завершуються, а не залишають абонентів у завислому стані в очікуванні завершення відтворення.
|
||||
- Коли barge-in Twilio або демонтаж потоку очищає чергу TTS, що очікує, запити відтворення в черзі завершуються, а не зависають для абонентів, які очікують завершення відтворення.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Core TTS only">
|
||||
<Tab title="Лише основний TTS">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -425,7 +425,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
<Tab title="Перевизначення на ElevenLabs (лише виклики)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -449,7 +449,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке об’єднання)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -486,21 +486,20 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller ID із низьким рівнем достовірності. Plugin
|
||||
`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низькою надійністю. Plugin
|
||||
нормалізує надане провайдером значення `From` і порівнює його з
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і
|
||||
цілісність корисного навантаження, але вона **не** доводить право власності
|
||||
на номер абонента PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller ID, а не як надійну
|
||||
цілісність payload, але **не** доводить володіння номером абонента
|
||||
PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію за ідентифікатором абонента, а не як сильну
|
||||
ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують систему агента. Налаштовуйте за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Контракт мовленнєвого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає строгий контракт мовленнєвого виводу до
|
||||
системного промпта:
|
||||
Для автовідповідей Voice Call додає до системного промпта суворий контракт мовленнєвого виводу:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
@ -508,23 +507,23 @@ Voice Call використовує основну конфігурацію `mes
|
||||
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує корисні навантаження, позначені як вміст міркувань або помилок.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту та видаляє ймовірні вступні абзаци планування чи метаданих.
|
||||
- Ігнорує payload, позначені як вміст міркування/помилки.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/мета-вмісту.
|
||||
|
||||
Це зберігає мовленнєве відтворення зосередженим на тексті для абонента та запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
Це утримує мовленнєве відтворення зосередженим на тексті для абонента й уникає
|
||||
витоку тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до живого
|
||||
стану відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення не вдається, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio починається після підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення та очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тому логіка наступної відповіді може продовжитися без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Голосові розмови Realtime використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються підключеними.
|
||||
- Очищення черги через barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
|
||||
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового передавання Twilio стартує під час підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка наступної відповіді може продовжити роботу без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Голосові розмови в реальному часі використовують власний початковий хід realtime-потоку. Voice Call **не** публікує застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються приєднаними.
|
||||
|
||||
### Пільговий період відключення потоку Twilio
|
||||
|
||||
@ -534,16 +533,16 @@ Voice Call захисно витягує текст мовлення:
|
||||
- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
|
||||
## Очищувач застарілих викликів
|
||||
## Прибирач застарілих викликів
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, що ніколи не завершуються). Типове значення —
|
||||
`0` (вимкнено).
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
|
||||
— `0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -562,28 +561,28 @@ Webhook (наприклад, виклики в режимі сповіщення
|
||||
|
||||
## Безпека Webhook
|
||||
|
||||
Коли проксі або тунель розташований перед Gateway, plugin
|
||||
реконструює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
керують тим, яким перенаправленим заголовкам можна довіряти:
|
||||
Коли проксі або тунель стоїть перед Gateway, plugin
|
||||
відтворює публічну URL-адресу для перевірки підпису. Ці параметри
|
||||
керують тим, яким перенаправленим заголовкам довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Дозволяє hosts із заголовків forwarding за списком allowlist.
|
||||
Список дозволених хостів із заголовків переспрямування.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряє перенаправленим заголовкам без allowlist.
|
||||
Довіряти перенаправленим заголовкам без списку дозволених.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряє перенаправленим заголовкам лише тоді, коли віддалена IP-адреса запиту відповідає списку.
|
||||
Довіряти перенаправленим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
|
||||
</ParamField>
|
||||
|
||||
Додаткові засоби захисту:
|
||||
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються щодо побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу у callback-ах `<Gather>`, тому застарілі або повторно відтворені callback-и мовлення не можуть задовольнити новіший очікуваний хід транскрипту.
|
||||
- Неавтентифіковані Webhook-запити відхиляються до читання тіла, якщо відсутні потрібні провайдером заголовки підпису.
|
||||
- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс обмеження одночасних запитів для кожної IP-адреси перед перевіркою підпису.
|
||||
- Захист Webhook **від повторного відтворення** увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються щодо побічних ефектів.
|
||||
- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах `<Gather>`, тому застарілі або повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід стенограми.
|
||||
- Неавтентифіковані запити Webhook відхиляються до читання тіла, коли відсутні обов’язкові заголовки підпису провайдера.
|
||||
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс обмеження одночасних запитів для кожної IP-адреси до перевірки підпису.
|
||||
|
||||
Приклад зі стабільним публічним host:
|
||||
Приклад зі стабільним публічним хостом:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -617,15 +616,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 voice-call, яким володіє Gateway, щоб CLI не прив’язував другий
|
||||
сервер Webhook. Якщо Gateway недосяжний, команди повертаються до
|
||||
автономного runtime CLI.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
|
||||
Використовуйте `--file <path>`, щоб вказати інший журнал, і `--last <n>`, щоб обмежити
|
||||
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
|
||||
для затримки ходу та часу очікування слухання.
|
||||
для затримки ходу та часу очікування прослуховування.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
@ -642,9 +641,9 @@ Webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
|
||||
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## RPC Gateway
|
||||
## Gateway RPC
|
||||
|
||||
| Метод | Аргументи |
|
||||
| Метод | Аргументи |
|
||||
| -------------------- | ------------------------- |
|
||||
| `voicecall.initiate` | `to?`, `message`, `mode?` |
|
||||
| `voicecall.continue` | `callId`, `message` |
|
||||
@ -653,8 +652,141 @@ Webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
### Не вдається налаштувати експонування Webhook
|
||||
|
||||
Запускайте налаштування з того самого середовища, у якому працює Gateway:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований
|
||||
`publicUrl` усе одно не спрацює, якщо він указує на локальний або приватний мережевий
|
||||
простір, бо оператор не може виконати callback на ці адреси. Не використовуйте
|
||||
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
|
||||
`192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`.
|
||||
|
||||
Використовуйте один публічний шлях експонування:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"voice-call": {
|
||||
config: {
|
||||
publicUrl: "https://voice.example.com/voice/webhook",
|
||||
// or
|
||||
tunnel: { provider: "ngrok" },
|
||||
// or
|
||||
tailscale: { mode: "funnel", path: "/voice/webhook" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Після зміни конфігурації перезапустіть або перезавантажте Gateway, потім виконайте:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` є пробним запуском, якщо не передати `--yes`.
|
||||
|
||||
### Помилка облікових даних провайдера
|
||||
|
||||
Перевірте вибраного провайдера та обов’язкові поля облікових даних:
|
||||
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber`, або
|
||||
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`.
|
||||
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` і
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`.
|
||||
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє
|
||||
середовище.
|
||||
|
||||
### Виклики запускаються, але вебхуки провайдера не надходять
|
||||
|
||||
Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу вебхука:
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
```
|
||||
|
||||
Потім перевірте стан виконання:
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
openclaw voicecall tail
|
||||
```
|
||||
|
||||
Поширені причини:
|
||||
|
||||
- `publicUrl` вказує на інший шлях, ніж `serve.path`.
|
||||
- URL тунелю змінився після запуску Gateway.
|
||||
- Проксі пересилає запит, але вилучає або переписує заголовки host/proto.
|
||||
- Фаєрвол або DNS спрямовує публічне ім'я хоста кудись, окрім Gateway.
|
||||
- Gateway було перезапущено без увімкненого Plugin Voice Call.
|
||||
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, задайте
|
||||
`webhookSecurity.allowedHosts` як публічне ім'я хоста або використайте
|
||||
`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте
|
||||
`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під
|
||||
вашим контролем.
|
||||
|
||||
### Не вдається перевірити підпис
|
||||
|
||||
Підписи провайдера перевіряються за публічною URL-адресою, яку OpenClaw відтворює
|
||||
з вхідного запиту. Якщо перевірка підписів не вдається:
|
||||
|
||||
- Переконайтеся, що URL-адреса вебхука провайдера точно збігається з `publicUrl`, включно зі
|
||||
схемою, хостом і шляхом.
|
||||
- Для URL-адрес безкоштовного рівня ngrok оновіть `publicUrl`, коли змінюється ім'я хоста тунелю.
|
||||
- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- Не вмикайте `skipSignatureVerification` поза локальним тестуванням.
|
||||
|
||||
### Не вдається приєднання Google Meet через Twilio
|
||||
|
||||
Google Meet використовує цей Plugin для приєднань через набір номера Twilio. Спочатку перевірте Voice Call:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Потім явно перевірте транспорт Google Meet:
|
||||
|
||||
```bash
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Якщо Voice Call працює, але учасник Meet так і не приєднується, перевірте номер
|
||||
дозвону Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
|
||||
зустріч відхиляє або ігнорує неправильну DTMF-послідовність.
|
||||
|
||||
### У виклику realtime немає мовлення
|
||||
|
||||
Переконайтеся, що увімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно мати значення true.
|
||||
|
||||
Для викликів Twilio у режимі realtime також перевірте:
|
||||
|
||||
- Plugin провайдера realtime завантажено й зареєстровано.
|
||||
- `realtime.provider` не задано або він називає зареєстрованого провайдера.
|
||||
- API-ключ провайдера доступний процесу Gateway.
|
||||
- `openclaw voicecall tail` показує, що медіапотік прийнято, а провайдер realtime готовий
|
||||
до початкового привітання.
|
||||
|
||||
## Пов'язане
|
||||
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Перетворення тексту на мовлення](/uk/tools/tts)
|
||||
- [Голосова активація](/uk/nodes/voicewake)
|
||||
- [Голосове пробудження](/uk/nodes/voicewake)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user