---
read_when:
- Зміна транскрибування аудіо або обробки медіафайлів
summary: Як вхідні аудіофайли й голосові нотатки завантажуються, транскрибуються та додаються до відповідей
title: Аудіо та голосові нотатки
x-i18n:
generated_at: "2026-07-12T13:24:26Z"
model: gpt-5.6
postprocess_version: locale-links-v1
provider: openai
source_hash: cb382f4219620d906bfa76ebddc690b174a3b24f80f815be92e915b363d17792
source_path: nodes/audio.md
workflow: 16
---
## Що це робить
Коли розуміння аудіо ввімкнено (або виявлено автоматично), OpenClaw:
1. Знаходить перше аудіовкладення (локальний шлях або URL) і за потреби завантажує його.
2. Застосовує обмеження `maxBytes` перед надсиланням до кожного запису моделі.
3. Послідовно запускає перший придатний запис моделі (провайдер або CLI); якщо запис завершується помилкою або пропускається (через розмір чи перевищення часу очікування), виконується спроба з наступним записом.
4. У разі успіху замінює `Body` блоком `[Audio]` і встановлює `{{Transcript}}`.
Після успішної транскрипції `CommandBody`/`RawBody` також отримують текст транскрипції, щоб команди з похилою рискою й надалі працювали. З параметром `--verbose` журнали показують, коли виконується транскрипція та коли вона замінює тіло повідомлення.
## Автоматичне виявлення (типово)
Якщо моделі не налаштовано й `tools.media.audio.enabled` не має значення `false`, OpenClaw виконує автоматичне виявлення в наведеному нижче порядку та зупиняється на першому працездатному варіанті:
1. **Активна модель відповіді**, якщо її провайдер підтримує розуміння аудіо.
2. **Налаштована автентифікація провайдера** — будь-який запис `models.providers.*` із доступною автентифікацією для провайдера, який підтримує транскрипцію аудіо. Цей варіант перевіряється перед локальними CLI, тому налаштований ключ API завжди має пріоритет над локальним виконуваним файлом у `PATH`.
Пріоритет провайдерів, коли налаштовано кілька: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral.
3. **Локальні CLI** (лише якщо не знайдено автентифікацію провайдера). OpenClaw формує впорядкований список резервних варіантів:
- `whisper-cli` перед типовими варіантами для CPU, лише якщо попередній виклик моделі в поточному процесі виявив Metal або CUDA
- `sherpa-onnx-offline` із типовим провайдером CPU (потребує `SHERPA_ONNX_MODEL_DIR` із файлами `tokens.txt`, `encoder.onnx`, `decoder.onnx` і `joiner.onnx`)
- `whisper-cli`, якщо збірка лише підтримує Metal/CUDA або вибрану серверну частину ще не було виявлено
- `parakeet-mlx` на Apple Silicon (підтримує MLX; використання пристрою залишається невиявленим)
- `whisper` (CLI для Python; автоматично завантажує моделі)
Походження встановлення чи посилання є свідченням підтримки можливості, а не її фактичного виконання. Саме собою воно ніколи не переміщує кандидата вище за sherpa для CPU. OpenClaw не завантажує модель під час налаштування чи перевірки стану лише для визначення серверної частини.
Автоматично виявлений whisper.cpp залишає ввімкненими звичайні журнали запуску моделі, щоб OpenClaw міг зафіксувати рядок `using … backend` від базового компонента. Явно задані записи CLI зберігають налаштовані прапорці виведення.
Автоматичне виявлення Gemini CLI для розуміння медіа замінено резервним варіантом ізольованого CLI Antigravity (`agy`) для зображень і відео; для аудіо не використовується жодний резервний CLI, окрім наведених вище локальних виконуваних файлів.
Щоб вимкнути автоматичне виявлення, задайте `tools.media.audio.enabled: false`. Щоб налаштувати його, задайте `tools.media.audio.models`.
Виявлення виконуваних файлів у macOS/Linux/Windows виконується за принципом найкращих зусиль. Переконайтеся, що CLI доступний у `PATH` (`~` розгортається), або задайте явну модель CLI з повним шляхом до команди.
Перевірте локальний вибір без транскрибування аудіо:
```bash
openclaw capability audio providers
openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info
```
Інвентаризація провайдерів окремо повідомляє переможця серед локальних резервних варіантів і глобальний вибір провайдера, а також поля підтримуваної, запитаної та виявленої серверної частини. Після виконання транскрипції `/status` показує запитану або виявлену серверну частину в рядку медіа. Явні записи CLI у `tools.media.audio.models` і надалі оминають автоматичний вибір; використовуйте відповідні їхній серверній частині прапорці, як-от `--provider=cuda` для sherpa або `--no-gpu`/`--device` для whisper.cpp.
## Приклади конфігурації
### Провайдер і резервний CLI (OpenAI + Whisper CLI)
```json5
{
tools: {
media: {
audio: {
enabled: true,
maxBytes: 20971520,
models: [
{ provider: "openai", model: "gpt-4o-transcribe" },
{
type: "cli",
command: "whisper",
args: ["--model", "base", "{{MediaPath}}"],
timeoutSeconds: 45,
},
],
},
},
},
}
```
### Лише провайдер з обмеженням області застосування
```json5
{
tools: {
media: {
audio: {
enabled: true,
scope: {
default: "allow",
rules: [{ action: "deny", match: { chatType: "group" } }],
},
models: [{ provider: "openai", model: "gpt-4o-transcribe" }],
},
},
},
}
```
### Лише провайдер (Deepgram)
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "deepgram", model: "nova-3" }],
},
},
},
}
```
### Лише провайдер (Mistral Voxtral)
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
},
},
},
}
```
### Лише провайдер (SenseAudio)
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
},
},
},
}
```
### Відтворення транскрипції в чаті (за явною згодою)
```json5
{
tools: {
media: {
audio: {
enabled: true,
echoTranscript: true, // типове значення — false
echoFormat: '📝 "{transcript}"', // необов’язково, підтримує {transcript}
models: [{ provider: "openai", model: "gpt-4o-transcribe" }],
},
},
},
}
```
## Примітки та обмеження
- Автентифікація провайдера відповідає стандартному порядку автентифікації моделей (профілі автентифікації, змінні середовища, `models.providers.*.apiKey`).
- Відомості про налаштування Groq: [Groq](/uk/providers/groq).
- Deepgram використовує `DEEPGRAM_API_KEY`, коли задано `provider: "deepgram"`. Відомості про налаштування: [Deepgram](/uk/providers/deepgram).
- Відомості про налаштування Mistral: [Mistral](/uk/providers/mistral).
- SenseAudio використовує `SENSEAUDIO_API_KEY`, коли задано `provider: "senseaudio"`. Відомості про налаштування: [SenseAudio](/uk/providers/senseaudio).
- Провайдери аудіо можуть перевизначати `baseUrl`, `headers` і `providerOptions` через `tools.media.audio`.
- Типове обмеження розміру становить 20 МБ (`tools.media.audio.maxBytes`). Завелике аудіо пропускається для цієї моделі, після чого виконується спроба з наступним записом.
- Аудіофайли розміром менше ніж 1024 байти пропускаються до транскрипції через провайдера або CLI.
- Типове значення `maxChars` для аудіо **не задано** (повна транскрипція). Задайте `tools.media.audio.maxChars` або `maxChars` для окремого запису, щоб скоротити результат.
- Типова модель автоматичного виявлення OpenAI — `gpt-4o-transcribe`; задайте `model: "gpt-4o-mini-transcribe"` для дешевшого та швидшого варіанта.
- Використовуйте `tools.media.audio.attachments`, щоб обробляти кілька голосових повідомлень (`mode: "all"` разом із `maxAttachments`, типове значення — 1).
- Транскрипція доступна в шаблонах як `{{Transcript}}`.
- `tools.media.audio.echoTranscript` типово вимкнено; увімкніть цей параметр, щоб до обробки агентом надсилати підтвердження транскрипції назад у початковий чат.
- `tools.media.audio.echoFormat` налаштовує текст відтворення (заповнювач: `{transcript}`; типове значення — `📝 "{transcript}"`).
- Обсяг стандартного виведення CLI обмежено 5 МБ; забезпечте стислий результат CLI.
- `args` CLI мають використовувати `{{MediaPath}}` для локального шляху до аудіофайлу. Запустіть `openclaw doctor --fix`, щоб перенести застарілі заповнювачі `{input}` зі старіших конфігурацій `audio.transcription.command` (вилучений ключ: `audio.transcription`, замінений на `tools.media.audio.models`).
- `tools.media.concurrency` обмежує кількість завдань обробки медіа; це не планувальник GPU.
### Постійно запущене локальне перетворення мовлення на текст
Автоматично виявлене локальне перетворення мовлення на текст і надалі запускає окремий процес для кожного запиту. Наразі OpenClaw не керує постійно запущеним сервером whisper.cpp, оскільки стандартний пакет Homebrew `whisper-cpp` вимикає цей сервер, а базовий приклад не має налаштованої обмеженої черги допуску. Щоб безпечно ввімкнути керований Plugin життєвий цикл постійно запущеного процесу, потрібен супроводжуваний пакетований обробник із перевіркою справності та запуску, постійним утриманням моделі в пам’яті, обмеженою чергою, скасуванням і часом очікування, роботою лише через local loopback без автентифікації та без резервного переходу до хмарного сервісу.
### Підтримка проксі через змінні середовища
Транскрипція аудіо на основі провайдерів враховує стандартні змінні середовища вихідного проксі відповідно до семантики `EnvHttpProxyAgent` в undici:
- `HTTPS_PROXY` / `https_proxy`
- `HTTP_PROXY` / `http_proxy`
- `ALL_PROXY` / `all_proxy`
Змінні в нижньому регістрі мають пріоритет над змінними у верхньому; записи `NO_PROXY`/`no_proxy` (імена хостів, `*.suffix` або `host:port`) оминають проксі. Якщо змінні середовища проксі не задано, використовується пряме вихідне з’єднання. Якщо налаштування проксі завершується помилкою (неправильно сформований URL), OpenClaw записує попередження в журнал і повертається до прямого отримання даних.
## Виявлення згадок у групах
У каналах, які підтримують попередню обробку аудіо, OpenClaw транскрибує аудіо **до** перевірки згадок, коли для групового чату задано `requireMention: true`. Завдяки цьому голосове повідомлення без підпису може пройти перевірку згадки, якщо його транскрипція містить налаштований шаблон згадки. У документації окремих каналів описано транспорти, які натомість потребують введеної текстом згадки.
**Як це працює:**
1. Якщо голосове повідомлення не має текстового тіла, а група вимагає згадок, OpenClaw виконує попередню транскрипцію першого аудіовкладення.
2. Транскрипція перевіряється на шаблони згадок (наприклад, `@BotName`, тригери-емодзі).
3. Якщо згадку знайдено, повідомлення проходить повний конвеєр формування відповіді.
**Резервна поведінка:** якщо попередня транскрипція завершується невдало (перевищення часу очікування, помилка API тощо), повідомлення повертається до виявлення згадок лише в тексті, тому змішані повідомлення (текст і аудіо) ніколи не відкидаються.
**Вимкнення для окремої групи або теми Telegram:**
- Задайте `channels.telegram.groups..disableAudioPreflight: true`, щоб пропустити попередню перевірку згадок у транскрипції для цієї групи.
- Задайте `channels.telegram.groups..topics..disableAudioPreflight`, щоб перевизначити значення для окремої теми (`true` — пропустити, `false` — примусово ввімкнути).
- Типове значення — `false` (попередню обробку ввімкнено, коли виконуються умови перевірки згадки).
**Приклад:** користувач надсилає голосове повідомлення зі словами «Привіт, @Claude, яка погода?» у групі Telegram із `requireMention: true`. Голосове повідомлення транскрибується, згадка виявляється, і агент відповідає.
## Підводні камені
- У правилах області застосування перший збіг має пріоритет; `chatType` нормалізується до `direct`, `group` або `channel`.
- Переконайтеся, що ваш CLI завершується з кодом 0 і виводить звичайний текст; виведення JSON потрібно обробити за допомогою `jq -r .text`.
- Відомі режими виведення у файл є визначальними: порожній або відсутній передбачуваний файл транскрипції не створює транскрипції замість резервного використання виведення перебігу роботи CLI.
- Для `parakeet-mlx` використовуйте `--output-format txt` (або `all`) разом із `--output-dir` і типовим шаблоном виведення `{filename}`. Також враховуються змінні середовища базового компонента `PARAKEET_OUTPUT_FORMAT` і `PARAKEET_OUTPUT_TEMPLATE`. OpenClaw читає `/.txt`; типовий формат `srt`, інші формати та власні шаблони виведення й надалі використовують стандартне виведення.
- Задавайте прийнятний час очікування (`timeoutSeconds`, типово 60 с), щоб не блокувати чергу відповідей.
- Для виявлення згадок попередня транскрипція обробляє лише **перше** аудіовкладення. Додаткові аудіовкладення обробляються під час основного етапу розуміння медіа.
## Пов’язані матеріали
- [Розуміння медіа](/uk/nodes/media-understanding)
- [Режим розмови](/uk/nodes/talk)
- [Голосова активація](/uk/nodes/voicewake)