Аудіо та голосові нотатки

Що це робить

Коли розуміння аудіо ввімкнено (або виявлено автоматично), 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.

Перевірте локальний вибір без транскрибування аудіо:

openclaw capability audio providersopenclaw 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)

{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{MediaPath}}"],            timeoutSeconds: 45,          },        ],      },    },  },}

Лише провайдер з обмеженням області застосування

{  tools: {    media: {      audio: {        enabled: true,        scope: {          default: "allow",          rules: [{ action: "deny", match: { chatType: "group" } }],        },        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],      },    },  },}

Лише провайдер (Deepgram)

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "deepgram", model: "nova-3" }],      },    },  },}

Лише провайдер (Mistral Voxtral)

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],      },    },  },}

Лише провайдер (SenseAudio)

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],      },    },  },}

Відтворення транскрипції в чаті (за явною згодою)

{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true, // типове значення — false        echoFormat: '📝 "{transcript}"', // необов’язково, підтримує {transcript}        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],      },    },  },}

Примітки та обмеження

• Автентифікація провайдера відповідає стандартному порядку автентифікації моделей (профілі автентифікації, змінні середовища, models.providers.*.apiKey).
• Відомості про налаштування Groq: Groq.
• Deepgram використовує DEEPGRAM_API_KEY, коли задано provider: "deepgram". Відомості про налаштування: Deepgram.
• Відомості про налаштування Mistral: Mistral.
• SenseAudio використовує SENSEAUDIO_API_KEY, коли задано provider: "senseaudio". Відомості про налаштування: 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.<chatId>.disableAudioPreflight: true, щоб пропустити попередню перевірку згадок у транскрипції для цієї групи.
• Задайте channels.telegram.groups.<chatId>.topics.<threadId>.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 читає <output-dir>/<media-basename>.txt; типовий формат srt, інші формати та власні шаблони виведення й надалі використовують стандартне виведення.
• Задавайте прийнятний час очікування (timeoutSeconds, типово 60 с), щоб не блокувати чергу відповідей.
• Для виявлення згадок попередня транскрипція обробляє лише перше аудіовкладення. Додаткові аудіовкладення обробляються під час основного етапу розуміння медіа.

Пов’язані матеріали

• Розуміння медіа
• Режим розмови
• Голосова активація