Аудио и голосовые заметки

Что работает

• Понимание медиа (аудио): если понимание аудио включено (или обнаружено автоматически), OpenClaw:
  1. Находит первое аудиовложение (локальный путь или URL) и при необходимости скачивает его.
  2. Применяет maxBytes перед отправкой каждой записи модели.
  3. Запускает первую подходящую запись модели по порядку (провайдер или CLI).
  4. Если она завершается ошибкой или пропускается (размер/тайм-аут), пробует следующую запись.
  5. При успехе заменяет Body блоком [Audio] и задает {{Transcript}}.
• Разбор команд: когда транскрибация успешна, CommandBody/RawBody получают значение транскрипта, поэтому слэш-команды продолжают работать.
• Подробное логирование: в режиме --verbose мы логируем, когда запускается транскрибация и когда она заменяет тело.

Автообнаружение (по умолчанию)

Если вы не настраиваете модели и tools.media.audio.enabled не задано как false, OpenClaw выполняет автообнаружение в этом порядке и останавливается на первом рабочем варианте:

1. Активная модель ответа, если ее провайдер поддерживает понимание аудио.
2. Локальные CLI (если установлены)
   • sherpa-onnx-offline (требует SHERPA_ONNX_MODEL_DIR с encoder/decoder/joiner/tokens)
   • whisper-cli (из whisper-cpp; использует WHISPER_CPP_MODEL или встроенную tiny-модель)
   • whisper (Python CLI; скачивает модели автоматически)
3. Авторизация провайдера
   • Сначала пробуются настроенные записи models.providers.*, поддерживающие аудио
   • Порядок резервных провайдеров: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

По состоянию на 2026-05-22 автообнаружение Gemini CLI больше не поддерживается для понимания медиа. Google переводит пользователей Gemini CLI на Antigravity CLI; для аудио следует использовать локальную или провайдерскую транскрибацию, а резервный CLI для изображений/видео следует перенести на Antigravity CLI (agy).

Чтобы отключить автообнаружение, задайте tools.media.audio.enabled: false. Чтобы настроить вручную, задайте tools.media.audio.models. Примечание: обнаружение бинарных файлов выполняется по мере возможности на macOS/Linux/Windows; убедитесь, что CLI находится в PATH (мы раскрываем ~), или задайте явную CLI-модель с полным путем к команде.

Примеры конфигурации

Провайдер + резервный CLI (OpenAI + Whisper CLI)

{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-mini-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-mini-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, // default is false        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],      },    },  },}

Примечания и ограничения

• Авторизация провайдера следует стандартному порядку авторизации моделей (профили авторизации, переменные окружения, models.providers.*.apiKey).
• Подробности настройки Groq: Groq.
• Deepgram подхватывает DEEPGRAM_API_KEY, когда используется provider: "deepgram".
• Подробности настройки Deepgram: Deepgram (транскрибация аудио).
• Подробности настройки Mistral: Mistral.
• SenseAudio подхватывает SENSEAUDIO_API_KEY, когда используется provider: "senseaudio".
• Подробности настройки SenseAudio: SenseAudio.
• Аудиопровайдеры могут переопределять baseUrl, headers и providerOptions через tools.media.audio.
• Ограничение размера по умолчанию — 20MB (tools.media.audio.maxBytes). Слишком большое аудио пропускается для этой модели, и пробуется следующая запись.
• Крошечные/пустые аудиофайлы меньше 1024 байт пропускаются перед транскрибацией через провайдера/CLI.
• Значение maxChars по умолчанию для аудио не задано (полный транскрипт). Задайте tools.media.audio.maxChars или maxChars для отдельной записи, чтобы обрезать вывод.
• Автоматическое значение OpenAI по умолчанию — gpt-4o-mini-transcribe; задайте model: "gpt-4o-transcribe" для более высокой точности.
• Используйте tools.media.audio.attachments, чтобы обработать несколько голосовых заметок (mode: "all" + maxAttachments).
• Транскрипт доступен шаблонам как {{Transcript}}.
• tools.media.audio.echoTranscript по умолчанию выключен; включите его, чтобы отправлять подтверждение транскрипта обратно в исходный чат до обработки агентом.
• tools.media.audio.echoFormat настраивает текст эха (заполнитель: {transcript}).
• stdout CLI ограничен (5MB); делайте вывод CLI кратким.
• args CLI должны использовать {{MediaPath}} для локального пути к аудиофайлу. Запустите openclaw doctor --fix, чтобы перенести устаревшие заполнители {input} из старых конфигураций audio.transcription.command.

Поддержка прокси через окружение

Аудиотранскрибация на основе провайдера учитывает стандартные переменные окружения для исходящего прокси:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

Если переменные окружения прокси не заданы, используется прямое исходящее подключение. Если конфигурация прокси некорректна, OpenClaw логирует предупреждение и возвращается к прямой загрузке.

Обнаружение упоминаний в группах

Когда для группового чата задано requireMention: true, OpenClaw теперь транскрибирует аудио до проверки упоминаний. Это позволяет обрабатывать голосовые заметки, даже когда они содержат упоминания.

Как это работает:

1. Если у голосового сообщения нет текстового тела, а группа требует упоминаний, OpenClaw выполняет «предварительную» транскрибацию.
2. Транскрипт проверяется на шаблоны упоминаний (например, @BotName, триггеры-эмодзи).
3. Если упоминание найдено, сообщение проходит через полный конвейер ответа.
4. Транскрипт используется для обнаружения упоминаний, чтобы голосовые заметки могли пройти фильтр упоминаний.

Резервное поведение:

• Если транскрибация завершается ошибкой во время предварительной проверки (тайм-аут, ошибка 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 или room.
• Убедитесь, что ваш CLI завершается с кодом 0 и печатает обычный текст; JSON нужно обработать через jq -r .text.
• Для parakeet-mlx, если вы передаете --output-dir, OpenClaw читает <output-dir>/<media-basename>.txt, когда --output-format равен txt (или опущен); форматы вывода не txt возвращаются к разбору stdout.
• Держите тайм-ауты разумными (timeoutSeconds, по умолчанию 60s), чтобы не блокировать очередь ответов.
• Предварительная транскрибация обрабатывает только первое аудиовложение для обнаружения упоминаний. Дополнительные аудиофайлы обрабатываются во время основной фазы понимания медиа.

Связанные материалы

• Понимание медиа
• Режим разговора
• Голосовое пробуждение