Медиа и устройства

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

Что работает

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

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

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

Локальные CLI (если установлены)
- sherpa-onnx-offline (требует SHERPA_ONNX_MODEL_DIR с encoder/decoder/joiner/tokens)
- whisper-cli (из whisper-cpp; использует WHISPER_CPP_MODEL или встроенную tiny-модель)
- whisper (Python CLI; автоматически загружает модели)
Gemini CLI (gemini) с использованием read_many_files
Ключи провайдеров (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,
          },
        ],
      },
    },
  },
}

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

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

Отправка транскрипции в чат (опционально)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // по умолчанию false
        echoFormat: '📝 "{transcript}"', // опционально, поддерживает {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

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

Аутентификация провайдера следует стандартному порядку (профили аутентификации, переменные окружения, models.providers.*.apiKey).
Deepgram использует DEEPGRAM_API_KEY, когда задан provider: "deepgram".
Подробности настройки Deepgram: Deepgram (транскрибация аудио).
Подробности настройки Mistral: Mistral.
Аудио-провайдеры могут переопределять baseUrl, headers и providerOptions через tools.media.audio.
Ограничение размера по умолчанию — 20 МБ (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}).
Вывод CLI ограничен (5 МБ); следите за лаконичностью вывода CLI.

Поддержка прокси-окружения

Транскрибация аудио через провайдера учитывает стандартные переменные окружения для исходящего прокси:

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

Если переменные окружения для прокси не заданы, используется прямое соединение. Если конфигурация прокси некорректна, OpenClaw логирует предупреждение и переключается на прямое соединение.

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

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

Если голосовое сообщение не содержит текста и группа требует упоминаний, OpenClaw выполняет "предварительную" транскрибацию.
Транскрипция проверяется на наличие паттернов упоминаний (например, @ИмяБота, триггеры-эмодзи).
Если упоминание найдено, сообщение проходит через полный конвейер ответа.
Транскрипция используется для обнаружения упоминаний, чтобы голосовые заметки могли пройти проверку.

Резервное поведение:

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

Отключение для конкретной группы/темы Telegram:

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

Пример: Пользователь отправляет голосовую заметку "Эй @Claude, какая погода?" в группу Telegram с requireMention: true. Голосовая заметка транскрибируется, упоминание обнаруживается, и агент отвечает.

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

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

Поддержка изображений и медиа Захват с камеры