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

​

Что работает

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

​

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

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

​

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

​

Провайдер + резервный 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

​

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

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

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

• Задайте channels.telegram.groups.<chatId>.disableAudioPreflight: true, чтобы пропустить предварительные проверки упоминаний по транскрипту для этой группы.
• Задайте channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight, чтобы переопределить для отдельной темы (true — пропустить, false — принудительно включить).
• По умолчанию — false (предварительная проверка включена, когда совпадают условия с фильтром упоминаний).

​

Важные нюансы

• Правила области действия используют первое совпадение. 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), чтобы не блокировать очередь ответов.
• Предварительная транскрибация обрабатывает только первое аудиовложение для обнаружения упоминаний. Дополнительные аудиофайлы обрабатываются во время основной фазы понимания медиа.

​

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

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