Аудио / Голосовые заметки — 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. Примечание: Обнаружение бинарных файлов выполняется с максимальными усилиями для 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.
  • Ограничение размера по умолчанию составляет 20 МБ (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\}\}.
  • Вывод CLI ограничен (5 МБ); сохраняйте вывод CLI кратким.

Подводные камни

  • Правила области применяют первое совпадение выигрывает. chatType нормализуется до direct, group или room.
  • Убедитесь, что ваш CLI завершается с кодом 0 и выводит простой текст; JSON нужно обрабатывать через jq -r .text.
  • Устанавливайте разумные тайм-ауты (timeoutSeconds, по умолчанию 60s), чтобы избежать блокировки очереди ответов.
← Назад к документации