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

Готчас¶

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