​

Audio / notatki głosowe (2026-01-17)

​

Co działa

• Rozumienie multimediów (audio): jeśli rozumienie audio jest włączone (lub wykrywane automatycznie), OpenClaw:
  1. Lokalizuje pierwszy załącznik audio (ścieżka lokalna lub URL) i pobiera go w razie potrzeby.
  2. Egzekwuje maxBytes przed wysłaniem do każdego wpisu modelu.
  3. Uruchamia pierwszy kwalifikujący się wpis modelu zgodnie z kolejnością (provider lub CLI).
  4. Jeśli to się nie powiedzie lub zostanie pominięte (rozmiar/timeout), próbuje następnego wpisu.
  5. Po sukcesie zastępuje Body blokiem [Audio] i ustawia {{Transcript}}.
• Parsowanie poleceń: gdy transkrypcja zakończy się sukcesem, CommandBody/RawBody są ustawiane na transkrypt, dzięki czemu polecenia slash nadal działają.
• Szczegółowe logowanie: w --verbose logujemy moment uruchomienia transkrypcji oraz moment zastąpienia treści.

​

Automatyczne wykrywanie (domyślne)

1. Aktywny model odpowiedzi, jeśli jego provider obsługuje rozumienie audio.
2. Lokalne CLI (jeśli są zainstalowane)
   • sherpa-onnx-offline (wymaga SHERPA_ONNX_MODEL_DIR z encoder/decoder/joiner/tokens)
   • whisper-cli (z whisper-cpp; używa WHISPER_CPP_MODEL lub dołączonego małego modelu)
   • whisper (Python CLI; automatycznie pobiera modele)
3. Gemini CLI (gemini) używające read_many_files
4. Uwierzytelnianie providera
   • Najpierw próbowane są skonfigurowane wpisy models.providers.* obsługujące audio
   • Wbudowana kolejność fallbacku: OpenAI → Groq → Deepgram → Google → Mistral

​

Przykłady konfiguracji

​

Fallback providera + 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,
          },
        ],
      },
    },
  },
}

​

Tylko provider z gatingiem zakresu

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​

Tylko provider (Deepgram)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

​

Tylko provider (Mistral Voxtral)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

​

Odesłanie transkryptu do czatu (opt-in)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // domyślnie false
        echoFormat: '📝 "{transcript}"', // opcjonalne, obsługuje {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​

Uwagi i limity

• Uwierzytelnianie providera korzysta ze standardowej kolejności auth modeli (profile uwierzytelniania, zmienne env, models.providers.*.apiKey).
• Szczegóły konfiguracji Groq: Groq.
• Deepgram pobiera DEEPGRAM_API_KEY, gdy używane jest provider: "deepgram".
• Szczegóły konfiguracji Deepgram: Deepgram (transkrypcja audio).
• Szczegóły konfiguracji Mistral: Mistral.
• Providery audio mogą nadpisywać baseUrl, headers i providerOptions przez tools.media.audio.
• Domyślny limit rozmiaru to 20 MB (tools.media.audio.maxBytes). Zbyt duże audio jest pomijane dla danego modelu i próbowany jest następny wpis.
• Małe/puste pliki audio poniżej 1024 bajtów są pomijane przed transkrypcją przez providera/CLI.
• Domyślne maxChars dla audio jest nieustawione (pełny transkrypt). Ustaw tools.media.audio.maxChars lub maxChars dla konkretnego wpisu, aby przyciąć wynik.
• Domyślnym auto ustawieniem OpenAI jest gpt-4o-mini-transcribe; ustaw model: "gpt-4o-transcribe", aby uzyskać większą dokładność.
• Użyj tools.media.audio.attachments, aby przetwarzać wiele notatek głosowych (mode: "all" + maxAttachments).
• Transkrypt jest dostępny dla szablonów jako {{Transcript}}.
• tools.media.audio.echoTranscript jest domyślnie wyłączone; włącz je, aby wysyłać potwierdzenie transkryptu z powrotem do czatu źródłowego przed przetwarzaniem przez agenta.
• tools.media.audio.echoFormat dostosowuje tekst echo (placeholder: {transcript}).
• stdout CLI jest ograniczone (5 MB); utrzymuj zwięzłe dane wyjściowe CLI.

​

Obsługa środowiska proxy

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Wykrywanie wzmianek w grupach

1. Jeśli wiadomość głosowa nie ma tekstowej treści, a grupa wymaga wzmianek, OpenClaw wykonuje transkrypcję „preflight”.
2. Transkrypt jest sprawdzany pod kątem wzorców wzmianek (na przykład @BotName, wyzwalaczy emoji).
3. Jeśli wzmianka zostanie znaleziona, wiadomość przechodzi przez pełny pipeline odpowiedzi.
4. Transkrypt jest używany do wykrywania wzmianek, dzięki czemu notatki głosowe mogą przejść przez bramkę wzmianki.

• Jeśli transkrypcja nie powiedzie się podczas preflight (timeout, błąd API itp.), wiadomość jest przetwarzana na podstawie wykrywania wzmianek wyłącznie z tekstu.
• Dzięki temu wiadomości mieszane (tekst + audio) nigdy nie są błędnie odrzucane.

• Ustaw channels.telegram.groups.<chatId>.disableAudioPreflight: true, aby pominąć kontrolę wzmianki w transkrypcie preflight dla tej grupy.
• Ustaw channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight, aby nadpisać to dla konkretnego tematu (true, aby pominąć, false, aby wymusić włączenie).
• Domyślna wartość to false (preflight włączony, gdy warunki gated wzmiankami pasują).

​

Pułapki

• Reguły zakresu używają zasady first-match wins. chatType jest normalizowane do direct, group lub room.
• Upewnij się, że Twoje CLI kończy się kodem 0 i wypisuje zwykły tekst; JSON trzeba przekształcić, na przykład przez jq -r .text.
• Dla parakeet-mlx, jeśli przekażesz --output-dir, OpenClaw odczytuje <output-dir>/<media-basename>.txt, gdy --output-format ma wartość txt (lub jest pominięte); formaty wyjściowe inne niż txt wracają do parsowania stdout.
• Utrzymuj rozsądne timeouty (timeoutSeconds, domyślnie 60 s), aby nie blokować kolejki odpowiedzi.
• Transkrypcja preflight przetwarza tylko pierwszy załącznik audio do wykrywania wzmianek. Dodatkowe audio jest przetwarzane podczas głównej fazy rozumienia multimediów.