Audio e note vocali

​

Funzionamento

1. Individua il primo allegato audio (percorso locale o URL) e lo scarica, se necessario.
2. Applica maxBytes prima dell’invio a ciascuna voce di modello.
3. Esegue in ordine la prima voce di modello idonea (provider o CLI); se una voce non riesce o viene ignorata (dimensione/timeout), prova quella successiva.
4. In caso di esito positivo, sostituisce Body con un blocco [Audio] e imposta {{Transcript}}.

​

Rilevamento automatico (predefinito)

1. Modello di risposta attivo, quando il relativo provider supporta la comprensione audio.
2. Autenticazione del provider configurata — qualsiasi voce models.providers.* con autenticazione disponibile per un provider che supporta la trascrizione audio. Questa verifica avviene prima delle CLI locali, quindi una chiave API configurata ha sempre la precedenza su un binario locale in PATH. Priorità dei provider quando ne sono configurati più di uno: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral.
3. CLI locali (solo se non è stata risolta alcuna autenticazione del provider). OpenClaw crea un elenco ordinato di opzioni di ripiego:
   • whisper-cli, prima delle opzioni CPU predefinite solo quando una precedente invocazione del modello nel processo corrente ha rilevato Metal o CUDA
   • sherpa-onnx-offline con il relativo provider CPU predefinito (richiede SHERPA_ONNX_MODEL_DIR con tokens.txt, encoder.onnx, decoder.onnx e joiner.onnx)
   • whisper-cli quando Metal/CUDA è soltanto supportato dalla compilazione o il backend selezionato non è stato altrimenti rilevato
   • parakeet-mlx su Apple Silicon (compatibile con MLX; l’uso del dispositivo rimane non rilevato)
   • whisper (CLI Python; scarica automaticamente i modelli)

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

​

Esempi di configurazione

​

Provider + opzione CLI di ripiego (OpenAI + CLI Whisper)

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

​

Solo provider con limitazione dell’ambito

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

​

Solo provider (Deepgram)

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

​

Solo provider (Mistral Voxtral)

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

​

Solo provider (SenseAudio)

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

​

Invio della trascrizione nella chat (facoltativo)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // il valore predefinito è false
        echoFormat: '📝 "{transcript}"', // facoltativo, supporta {transcript}
        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],
      },
    },
  },
}

​

Note e limitazioni

• L’autenticazione del provider segue l’ordine standard di autenticazione dei modelli (profili di autenticazione, variabili di ambiente, models.providers.*.apiKey).
• Dettagli sulla configurazione di Groq: Groq.
• Deepgram usa DEEPGRAM_API_KEY quando viene utilizzato provider: "deepgram". Dettagli sulla configurazione: Deepgram.
• Dettagli sulla configurazione di Mistral: Mistral.
• SenseAudio usa SENSEAUDIO_API_KEY quando viene utilizzato provider: "senseaudio". Dettagli sulla configurazione: SenseAudio.
• I provider audio possono sostituire baseUrl, headers e providerOptions tramite tools.media.audio.
• Il limite di dimensione predefinito è 20 MB (tools.media.audio.maxBytes). L’audio che supera il limite viene ignorato per quel modello e viene provata la voce successiva.
• I file audio inferiori a 1024 byte vengono ignorati prima della trascrizione tramite provider/CLI.
• Il valore predefinito di maxChars per l’audio è non impostato (trascrizione completa). Imposta tools.media.audio.maxChars o un valore maxChars per singola voce per troncare l’output.
• Il valore predefinito del rilevamento automatico di OpenAI è gpt-4o-transcribe; imposta model: "gpt-4o-mini-transcribe" per un’opzione più economica e veloce.
• Usa tools.media.audio.attachments per elaborare più note vocali (mode: "all" insieme a maxAttachments, valore predefinito 1).
• La trascrizione è disponibile per i modelli tramite {{Transcript}}.
• tools.media.audio.echoTranscript è disabilitato per impostazione predefinita; abilitalo per inviare una conferma della trascrizione alla chat di origine prima dell’elaborazione da parte dell’agente.
• tools.media.audio.echoFormat personalizza il testo della conferma (segnaposto: {transcript}; valore predefinito 📝 "{transcript}").
• Lo stdout della CLI è limitato a 5 MB; mantieni conciso l’output della CLI.
• Gli args della CLI devono usare {{MediaPath}} per il percorso del file audio locale. Esegui openclaw doctor --fix per migrare i segnaposto {input} deprecati dalle configurazioni audio.transcription.command meno recenti (chiave ritirata: audio.transcription, sostituita da tools.media.audio.models).
• tools.media.concurrency limita le attività multimediali; non è uno scheduler per GPU.

​

STT locale residente

​

Supporto delle variabili di ambiente per proxy

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

​

Rilevamento delle menzioni nei gruppi

1. Se un messaggio vocale non contiene un corpo testuale e il gruppo richiede menzioni, OpenClaw esegue una trascrizione preliminare del primo allegato audio.
2. La trascrizione viene controllata alla ricerca di modelli di menzione (ad esempio @BotName, attivatori emoji).
3. Se viene trovata una menzione, il messaggio prosegue attraverso la pipeline di risposta completa.

• Imposta channels.telegram.groups.<chatId>.disableAudioPreflight: true per ignorare i controlli preliminari delle menzioni nella trascrizione per quel gruppo.
• Imposta channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight per sostituire l’impostazione per singolo argomento (true per ignorare, false per forzare l’abilitazione).
• Il valore predefinito è false (verifica preliminare abilitata quando corrispondono le condizioni che richiedono una menzione).

​

Aspetti da considerare

• Le regole di ambito usano la prima corrispondenza; chatType viene normalizzato in direct, group o channel.
• Assicurati che la CLI termini con codice 0 e stampi testo normale; l’output JSON deve essere rielaborato tramite jq -r .text.
• Le modalità note di output su file sono autorevoli: un file di trascrizione dedotto vuoto o mancante non produce alcuna trascrizione, anziché ricorrere all’output di avanzamento della CLI.
• Per parakeet-mlx, usa --output-format txt (o all) con --output-dir e il modello di output predefinito {filename}. Sono supportate anche le variabili di ambiente upstream PARAKEET_OUTPUT_FORMAT e PARAKEET_OUTPUT_TEMPLATE. OpenClaw legge <output-dir>/<media-basename>.txt; il formato predefinito srt, gli altri formati e i modelli di output personalizzati continuano a usare stdout.
• Mantieni timeout ragionevoli (timeoutSeconds, valore predefinito 60 s) per evitare di bloccare la coda delle risposte.
• La trascrizione preliminare elabora soltanto il primo allegato audio per il rilevamento delle menzioni. Gli allegati audio aggiuntivi vengono elaborati durante la fase principale di comprensione dei contenuti multimediali.

​

Voci correlate

• Comprensione dei contenuti multimediali
• Modalità conversazione
• Attivazione vocale