Notatki dźwiękowe i głosowe

Co to robi

Gdy rozumienie dźwięku jest włączone (lub wykryte automatycznie), OpenClaw:

1. Lokalizuje pierwszy załącznik audio (ścieżkę lokalną lub adres URL) i w razie potrzeby go pobiera.
2. Egzekwuje limit maxBytes przed wysłaniem do każdego wpisu modelu.
3. Uruchamia pierwszy kwalifikujący się wpis modelu w podanej kolejności (dostawca lub CLI); jeśli wpis zakończy się niepowodzeniem albo zostanie pominięty (rozmiar/przekroczenie limitu czasu), podejmowana jest próba użycia następnego wpisu.
4. Po powodzeniu zastępuje Body blokiem [Audio] i ustawia {{Transcript}}.

Po pomyślnej transkrypcji pola CommandBody/RawBody również otrzymują treść transkrypcji, dzięki czemu polecenia z ukośnikiem nadal działają. Przy użyciu --verbose dzienniki pokazują, kiedy wykonywana jest transkrypcja i kiedy zastępuje ona treść wiadomości.

Automatyczne wykrywanie (domyślne)

Jeśli nie skonfigurowano modeli, a tools.media.audio.enabled nie ma wartości false, OpenClaw automatycznie sprawdza poniższe opcje w podanej kolejności i zatrzymuje się na pierwszej działającej:

1. Aktywny model odpowiedzi, jeśli jego dostawca obsługuje rozumienie dźwięku.
2. Skonfigurowane uwierzytelnianie dostawcy — dowolny wpis models.providers.* z dostępnym uwierzytelnianiem dla dostawcy obsługującego transkrypcję dźwięku. Jest to sprawdzane przed lokalnymi narzędziami CLI, dlatego skonfigurowany klucz API zawsze ma pierwszeństwo przed lokalnym plikiem wykonywalnym w PATH. Priorytet dostawców, gdy skonfigurowano wielu: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral.
3. Lokalne narzędzia CLI (tylko jeśli nie znaleziono uwierzytelniania dostawcy). OpenClaw tworzy uporządkowaną listę opcji zapasowych:
   • whisper-cli, przed domyślnymi opcjami procesora CPU tylko wtedy, gdy wcześniejsze wywołanie modelu w bieżącym procesie wykryło Metal lub CUDA
   • sherpa-onnx-offline z domyślnym dostawcą CPU (wymaga SHERPA_ONNX_MODEL_DIR zawierającego tokens.txt, encoder.onnx, decoder.onnx i joiner.onnx)
   • whisper-cli, gdy kompilacja obsługuje jedynie Metal/CUDA albo wybrany backend nie został w inny sposób zaobserwowany
   • parakeet-mlx na Apple Silicon (obsługuje MLX; użycie urządzenia pozostaje niezaobserwowane)
   • whisper (CLI w Pythonie; automatycznie pobiera modele)

Pochodzenie instalacji lub dowiązania stanowi dowód możliwości, a nie wykonania. Samo w sobie nigdy nie przesuwa kandydata przed sherpa korzystającą z CPU. OpenClaw nie ładuje modelu podczas konfiguracji ani sprawdzania stanu wyłącznie w celu zbadania backendu. Automatycznie wykryty whisper.cpp zachowuje włączone standardowe dzienniki uruchomienia modelu, aby OpenClaw mógł zarejestrować pochodzący z niego wiersz using … backend. Jawne wpisy CLI zachowują skonfigurowane flagi wyjścia.

Automatyczne wykrywanie Gemini CLI na potrzeby rozumienia multimediów zastąpiono działającą w piaskownicy opcją zapasową Antigravity CLI (agy) dla obrazów i filmów; w przypadku dźwięku nie jest używana żadna opcja zapasowa CLI poza wymienionymi wyżej lokalnymi plikami wykonywalnymi.

Aby wyłączyć automatyczne wykrywanie, ustaw tools.media.audio.enabled: false. Aby je dostosować, ustaw tools.media.audio.models.

Sprawdź wybór lokalny bez wykonywania transkrypcji dźwięku:

openclaw capability audio providersopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Inwentarz dostawców raportuje zwycięską lokalną opcję zapasową oddzielnie od globalnego wyboru dostawcy, a także pola obsługiwanego, żądanego i zaobserwowanego backendu. Po wykonaniu transkrypcji /status podaje żądany lub zaobserwowany backend w wierszu multimediów. Jawne wpisy CLI w tools.media.audio.models nadal pomijają automatyczny wybór; używaj właściwych dla danego backendu flag, takich jak --provider=cuda dla sherpa lub --no-gpu/--device dla whisper.cpp.

Przykłady konfiguracji

Dostawca i zapasowe CLI (OpenAI + Whisper CLI)

{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{MediaPath}}"],            timeoutSeconds: 45,          },        ],      },    },  },}

Tylko dostawca z ograniczeniem zakresu

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

Tylko dostawca (Deepgram)

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

Tylko dostawca (Mistral Voxtral)

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

Tylko dostawca (SenseAudio)

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],      },    },  },}

Powtórzenie transkrypcji na czacie (opcjonalne)

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

Uwagi i ograniczenia

• Uwierzytelnianie dostawcy odbywa się zgodnie ze standardową kolejnością uwierzytelniania modeli (profile uwierzytelniania, zmienne środowiskowe, models.providers.*.apiKey).
• Szczegóły konfiguracji Groq: Groq.
• Deepgram pobiera wartość DEEPGRAM_API_KEY, gdy używane jest provider: "deepgram". Szczegóły konfiguracji: Deepgram.
• Szczegóły konfiguracji Mistral: Mistral.
• SenseAudio pobiera wartość SENSEAUDIO_API_KEY, gdy używane jest provider: "senseaudio". Szczegóły konfiguracji: SenseAudio.
• Dostawcy dźwięku mogą nadpisywać baseUrl, headers i providerOptions za pośrednictwem tools.media.audio.
• Domyślny limit rozmiaru wynosi 20 MB (tools.media.audio.maxBytes). Dźwięk przekraczający limit jest pomijany dla danego modelu i podejmowana jest próba użycia następnego wpisu.
• Pliki audio mniejsze niż 1024 bajty są pomijane przed transkrypcją przez dostawcę lub CLI.
• Domyślna wartość maxChars dla dźwięku jest nieustawiona (pełna transkrypcja). Ustaw tools.media.audio.maxChars lub maxChars dla konkretnego wpisu, aby skrócić dane wyjściowe.
• Domyślnym modelem automatycznego wykrywania OpenAI jest gpt-4o-transcribe; ustaw model: "gpt-4o-mini-transcribe", aby użyć tańszej i szybszej opcji.
• Użyj tools.media.audio.attachments, aby przetwarzać wiele notatek głosowych (mode: "all" wraz z maxAttachments, domyślnie 1).
• Transkrypcja jest dostępna w szablonach jako {{Transcript}}.
• tools.media.audio.echoTranscript jest domyślnie wyłączone; włącz tę opcję, aby przed przetwarzaniem przez agenta wysłać potwierdzenie transkrypcji z powrotem do czatu źródłowego.
• tools.media.audio.echoFormat dostosowuje tekst powtórzenia (symbol zastępczy: {transcript}; domyślnie 📝 "{transcript}").
• Standardowe wyjście CLI jest ograniczone do 5 MB; zadbaj o zwięzłe dane wyjściowe CLI.
• args narzędzia CLI powinno używać {{MediaPath}} jako lokalnej ścieżki pliku audio. Uruchom openclaw doctor --fix, aby zmigrować przestarzałe symbole zastępcze {input} ze starszych konfiguracji audio.transcription.command (wycofany klucz: audio.transcription, zastąpiony przez tools.media.audio.models).
• tools.media.concurrency ogranicza liczbę zadań multimedialnych; nie jest to harmonogram zadań GPU.

Rezydentne lokalne STT

Automatycznie wykrywane lokalne STT nadal działa w modelu osobnego procesu dla każdego żądania. OpenClaw nie zarządza obecnie rezydentnym serwerem whisper.cpp, ponieważ standardowy pakiet Homebrew whisper-cpp wyłącza ten serwer, a przykład z projektu źródłowego nie ma skonfigurowanej kolejki przyjmowania o ograniczonym rozmiarze. Aby można było bezpiecznie włączyć rezydentny cykl życia należący do pluginu, potrzebny jest utrzymywany, pakietowany proces roboczy z kontrolą kondycji i uruchamiania, trwałym załadowaniem modelu, ograniczonym kolejkowaniem, anulowaniem i limitami czasu, działaniem bez uwierzytelniania wyłącznie przez local loopback oraz bez zapasowego przełączania do chmury.

Obsługa środowiska proxy

Transkrypcja dźwięku oparta na dostawcach respektuje standardowe zmienne środowiskowe wychodzącego proxy zgodnie z semantyką EnvHttpProxyAgent z undici:

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy
• ALL_PROXY / all_proxy

Zmienne pisane małymi literami mają pierwszeństwo przed zmiennymi pisanymi wielkimi literami; wpisy NO_PROXY/no_proxy (nazwy hostów, *.suffix lub host:port) omijają proxy. Jeśli nie ustawiono żadnych zmiennych środowiskowych proxy, używane jest bezpośrednie połączenie wychodzące. Jeśli konfiguracja proxy się nie powiedzie (nieprawidłowy adres URL), OpenClaw zapisuje ostrzeżenie w dzienniku i przechodzi na bezpośrednie pobieranie.

Wykrywanie wzmianek w grupach

W kanałach obsługujących wstępne przetwarzanie dźwięku OpenClaw wykonuje transkrypcję przed sprawdzeniem wzmianek, gdy dla czatu grupowego ustawiono requireMention: true. Dzięki temu notatka głosowa bez podpisu może przejść kontrolę wzmianki, jeśli jej transkrypcja zawiera skonfigurowany wzorzec wzmianki. Dokumentacja poszczególnych kanałów opisuje transporty, które zamiast tego wymagają wpisanej wzmianki.

Jak to działa:

1. Jeśli wiadomość głosowa nie zawiera tekstu, a grupa wymaga wzmianek, OpenClaw wykonuje wstępną transkrypcję pierwszego załącznika audio.
2. Transkrypcja jest sprawdzana pod kątem wzorców wzmianek (na przykład @BotName, wyzwalaczy emoji).
3. Jeśli zostanie znaleziona wzmianka, wiadomość przechodzi przez pełny potok odpowiedzi.

Działanie zapasowe: jeśli wstępna transkrypcja się nie powiedzie (przekroczenie limitu czasu, błąd API itp.), wiadomość przechodzi na wykrywanie wzmianek wyłącznie w tekście, dzięki czemu wiadomości mieszane (tekst + dźwięk) nigdy nie są odrzucane.

Wyłączenie dla grupy lub tematu Telegramu:

• Ustaw channels.telegram.groups.<chatId>.disableAudioPreflight: true, aby pominąć wstępne sprawdzanie wzmianek w transkrypcji dla tej grupy.
• Ustaw channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight, aby nadpisać ustawienie dla danego tematu (true, aby pominąć; false, aby wymusić włączenie).
• Wartość domyślna to false (wstępne przetwarzanie jest włączone, gdy spełnione są warunki wymagania wzmianki).

Przykład: użytkownik wysyła w grupie Telegram z ustawieniem requireMention: true notatkę głosową o treści „Hej @Claude, jaka jest pogoda?”. Notatka głosowa zostaje przepisana, wzmianka zostaje wykryta, a agent odpowiada.

Pułapki

• Reguły zakresu stosują zasadę pierwszego dopasowania; chatType jest normalizowane do direct, group lub channel.
• Upewnij się, że CLI kończy działanie z kodem 0 i wyświetla zwykły tekst; dane wyjściowe JSON trzeba przekształcić za pomocą jq -r .text.
• Znane tryby zapisu do pliku są rozstrzygające: pusty lub brakujący wywnioskowany plik transkrypcji oznacza brak transkrypcji zamiast przejścia na dane o postępie z CLI.
• W przypadku parakeet-mlx użyj --output-format txt (lub all) wraz z --output-dir oraz domyślnym szablonem wyjściowym {filename}. Obsługiwane są również pochodzące z projektu źródłowego zmienne środowiskowe PARAKEET_OUTPUT_FORMAT i PARAKEET_OUTPUT_TEMPLATE. OpenClaw odczytuje <output-dir>/<media-basename>.txt; domyślny format srt, inne formaty i niestandardowe szablony wyjściowe nadal korzystają ze standardowego wyjścia.
• Ustawiaj rozsądne limity czasu (timeoutSeconds, domyślnie 60 s), aby uniknąć blokowania kolejki odpowiedzi.
• Wstępna transkrypcja przetwarza na potrzeby wykrywania wzmianek wyłącznie pierwszy załącznik audio. Dodatkowe załączniki audio są przetwarzane podczas głównego etapu rozumienia multimediów.

Powiązane

• Rozumienie multimediów
• Tryb rozmowy
• Wybudzanie głosowe