Перейти к основному содержанию

​
Аудио / голосовые заметки — 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)

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

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

  • Аутентификация провайдеров следует стандартному порядку аутентификации моделей (профили аутентификации, переменные окружения, models.providers.*.apiKey).
  • Deepgram подхватывает DEEPGRAM_API_KEY, когда используется provider: "deepgram".
  • Подробности настройки Deepgram: Deepgram (audio transcription).
  • Аудиопровайдеры могут переопределять 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-транскрибация обрабатывает только первое аудиовложение для обнаружения упоминаний. Дополнительные аудиофайлы обрабатываются на основном этапе анализа медиа.