Перейти до основного вмісту

​
Аудіо / голосові повідомлення (2026-01-17)

​
Що працює

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

​
Автовизначення (типово)

Якщо ви не налаштовуєте моделі і tools.media.audio.enabled не має значення false, OpenClaw виконує автовизначення в такому порядку й зупиняється на першому робочому варіанті:
  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. Gemini CLI (gemini) з використанням read_many_files
  4. Автентифікація провайдера
    • Спочатку пробуються налаштовані записи models.providers.*, які підтримують аудіо
    • Вбудований порядок fallback: OpenAI → Groq → Deepgram → Google → Mistral
Щоб вимкнути автовизначення, установіть tools.media.audio.enabled: false. Щоб налаштувати вручну, установіть tools.media.audio.models. Примітка: виявлення бінарних файлів працює за принципом best-effort на macOS/Linux/Windows; переконайтеся, що CLI є в PATH (ми розгортаємо ~), або задайте явну CLI-модель із повним шляхом до команди.

​
Приклади конфігурації

​
Провайдер + fallback через 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" }],
      },
    },
  },
}

​
Відлуння транскрипту в чат (opt-in)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // типово false
        echoFormat: '📝 "{transcript}"', // необов’язково, підтримує {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​
Примітки та обмеження

  • Автентифікація провайдера дотримується стандартного порядку автентифікації моделей (auth profiles, env vars, models.providers.*.apiKey).
  • Докладно про налаштування Groq: Groq.
  • Deepgram підхоплює DEEPGRAM_API_KEY, коли використовується provider: "deepgram".
  • Докладно про налаштування Deepgram: Deepgram (audio transcription).
  • Докладно про налаштування Mistral: Mistral.
  • Провайдери аудіо можуть перевизначати 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}).
  • Вивід CLI через stdout має обмеження (5MB); робіть вивід CLI стислим.

​
Підтримка проксі через змінні середовища

Транскрибування аудіо через провайдера враховує стандартні env vars для вихідного проксі:
  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy
Якщо env vars проксі не задані, використовується прямий вихід у мережу. Якщо конфігурація проксі некоректна, OpenClaw записує попередження в журнал і повертається до прямого fetch.

​
Виявлення згадок у групах

Коли для групового чату встановлено requireMention: true, OpenClaw тепер транскрибує аудіо до перевірки згадок. Це дає змогу обробляти голосові повідомлення навіть тоді, коли вони містять згадки. Як це працює:
  1. Якщо голосове повідомлення не має текстового body і для групи потрібні згадки, OpenClaw виконує “preflight” транскрибування.
  2. Транскрипт перевіряється на шаблони згадок (наприклад, @BotName, тригери emoji).
  3. Якщо згадку знайдено, повідомлення проходить через повний конвеєр відповіді.
  4. Транскрипт використовується для виявлення згадки, щоб голосові повідомлення могли пройти перевірку згадки.
Поведінка fallback:
  • Якщо транскрибування під час preflight завершується помилкою (тайм-аут, помилка API тощо), повідомлення обробляється на основі лише текстового виявлення згадки.
  • Це гарантує, що змішані повідомлення (текст + аудіо) ніколи не буде помилково відкинуто.
Opt-out для окремої групи/теми Telegram:
  • Установіть channels.telegram.groups.<chatId>.disableAudioPreflight: true, щоб пропустити preflight-перевірку згадок за транскриптом для цієї групи.
  • Установіть channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight, щоб перевизначити для окремої теми (true — пропустити, false — примусово ввімкнути).
  • Типове значення — false (preflight увімкнено, коли збігаються умови перевірки згадки).
Приклад: користувач надсилає голосове повідомлення зі словами “Hey @Claude, what’s the weather?” у групі Telegram з requireMention: true. Голосове повідомлення транскрибується, згадка виявляється, і агент відповідає.

​
Типові пастки

  • Правила scope використовують принцип first-match wins. 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), щоб не блокувати чергу відповідей.
  • Preflight-транскрибування обробляє лише перше аудіовкладення для виявлення згадки. Додаткове аудіо обробляється під час основної фази розуміння медіа.