OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

Аудио и голосовые сообщения

Что делает эта функция

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

Проверьте локальный выбор без транскрипции аудио:

bash
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)

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, // default is false        echoFormat: '📝 "{transcript}"', // optional, supports {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.
  • Стандартное ограничение размера — 20MB (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}").
  • Вывод stdout CLI ограничен 5MB; вывод 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 отключает этот сервер, а в примере вышестоящего проекта не настроена ограниченная очередь допуска. Чтобы безопасно включить резидентный жизненный цикл под управлением плагина, необходим сопровождаемый упакованный рабочий процесс с проверкой работоспособности и запуском, постоянным размещением модели, ограниченной очередью, отменой и тайм-аутом, работой только через 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 (предварительная обработка включается, когда выполняются условия обязательного упоминания).

Пример: пользователь отправляет в группу Telegram с requireMention: true голосовое сообщение: «Привет, @Claude, какая погода?». Голосовое сообщение транскрибируется, упоминание обнаруживается, и агент отвечает.

Возможные проблемы

  • Для правил области действия применяется первое совпадение; 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, другие форматы и пользовательские шаблоны вывода продолжают использовать stdout.
  • Устанавливайте разумные тайм-ауты (timeoutSeconds, стандартное значение 60s), чтобы не блокировать очередь ответов.
  • Для обнаружения упоминаний предварительная транскрипция обрабатывает только первое аудиовложение. Дополнительные аудиовложения обрабатываются на основном этапе распознавания медиа.

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

Was this useful?
On this page

On this page