> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Аудио / голосовые заметки — 2026-01-17

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

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

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

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

1. **Локальные CLI** (если установлены)
   * `sherpa-onnx-offline` (требуется `SHERPA_ONNX_MODEL_DIR` с encoder/decoder/joiner/tokens)
   * `whisper-cli` (из `whisper-cpp`; использует `WHISPER_CPP_MODEL` или встроенную tiny‑модель)
   * `whisper` (Python CLI; автоматически загружает модели)
2. **Gemini CLI** (`gemini`) с использованием `read_many_files`
3. **Ключи провайдеров** (OpenAI → Groq → Deepgram → Google)

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

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

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

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

### Только провайдер (Deepgram)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}
```

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

* Аутентификация провайдеров следует стандартному порядку аутентификации моделей (профили аутентификации, переменные окружения, `models.providers.*.apiKey`).
* Deepgram подхватывает `DEEPGRAM_API_KEY`, когда используется `provider: "deepgram"`.
* Подробности настройки Deepgram: [Deepgram (audio transcription)](/providers/deepgram).
* Аудиопровайдеры могут переопределять `baseUrl`, `headers` и `providerOptions` через `tools.media.audio`.
* Ограничение размера по умолчанию — 20MB (`tools.media.audio.maxBytes`). Слишком большое аудио пропускается для этой модели, и пробуется следующий элемент.
* Значение `maxChars` для аудио по умолчанию **не задано** (полная транскрипция). Установите `tools.media.audio.maxChars` или `maxChars` для отдельного элемента, чтобы обрезать вывод.
* Автозначение OpenAI по умолчанию — `gpt-4o-mini-transcribe`; установите `model: "gpt-4o-transcribe"` для более высокой точности.
* Используйте `tools.media.audio.attachments` для обработки нескольких голосовых заметок (`mode: "all"` + `maxAttachments`).
* Транскрипт доступен в шаблонах как `{{Transcript}}`.
* Вывод stdout CLI ограничен (5MB); держите вывод CLI кратким.

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

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

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

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

**Поведение при сбое:**

* Если транскрибация завершается ошибкой на этапе preflight (тайм-аут, ошибка API и т. д.), сообщение обрабатывается на основе обнаружения упоминаний только в тексте.
* Это гарантирует, что смешанные сообщения (текст + аудио) никогда не будут ошибочно отклонены.

**Пример:** Пользователь отправляет голосовое сообщение «Hey @Claude, what's the weather?» в группе Telegram с `requireMention: true`. Голосовое сообщение транскрибируется, обнаруживается упоминание, и агент отвечает.

## Готчас

* Правила областей используют принцип «первое совпадение выигрывает». `chatType` нормализуется к `direct`, `group` или `room`.
* Убедитесь, что ваш CLI завершает работу с кодом 0 и печатает обычный текст; JSON необходимо привести к нужному виду через `jq -r .text`.
* Держите тайм‑ауты разумными (`timeoutSeconds`, по умолчанию 60с), чтобы не блокировать очередь ответов.
* Preflight-транскрибация обрабатывает только **первое** аудиовложение для обнаружения упоминаний. Дополнительные аудиофайлы обрабатываются на основном этапе анализа медиа.