---
read_when:
    - Изменение транскрибации аудио или обработки медиа
summary: Как входящие аудио и голосовые сообщения скачиваются, транскрибируются и добавляются в ответы
title: Аудио и голосовые заметки
x-i18n:
    generated_at: "2026-06-28T23:08:49Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 90e66cf76537b090afdcd3a7791b40107ae51d6be89c84fcb14c034e38df875e
    source_path: nodes/audio.md
    workflow: 16
---

## Что работает

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

```json5
{
  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,
          },
        ],
      },
    },
  },
}
```

### Только провайдер с ограничением по области действия

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-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-mini-transcribe" }],
      },
    },
  },
}
```

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

- Авторизация провайдера следует стандартному порядку авторизации моделей (профили авторизации, переменные окружения, `models.providers.*.apiKey`).
- Подробности настройки Groq: [Groq](/ru/providers/groq).
- Deepgram подхватывает `DEEPGRAM_API_KEY`, когда используется `provider: "deepgram"`.
- Подробности настройки Deepgram: [Deepgram (транскрибация аудио)](/ru/providers/deepgram).
- Подробности настройки Mistral: [Mistral](/ru/providers/mistral).
- SenseAudio подхватывает `SENSEAUDIO_API_KEY`, когда используется `provider: "senseaudio"`.
- Подробности настройки SenseAudio: [SenseAudio](/ru/providers/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), чтобы не блокировать очередь ответов.
- Предварительная транскрибация обрабатывает только **первое** аудиовложение для обнаружения упоминаний. Дополнительные аудиофайлы обрабатываются во время основной фазы понимания медиа.

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

- [Понимание медиа](/ru/nodes/media-understanding)
- [Режим разговора](/ru/nodes/talk)
- [Голосовое пробуждение](/ru/nodes/voicewake)