> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Áudio e Notas de Voz

# Áudio / Notas de Voz — 2026-01-17

## O que funciona

* **Compreensão de mídia (áudio)**: Se a compreensão de áudio estiver habilitada (ou detectada automaticamente), o OpenClaw:
  1. Localiza o primeiro anexo de áudio (caminho local ou URL) e faz o download se necessário.
  2. Aplica `maxBytes` antes de enviar para cada entrada de modelo.
  3. Executa a primeira entrada de modelo elegível em ordem (provedor ou CLI).
  4. Se falhar ou pular (tamanho/timeout), tenta a próxima entrada.
  5. Em caso de sucesso, substitui `Body` por um bloco `[Audio]` e define `{{Transcript}}`.
* **Análise de comandos**: Quando a transcrição é bem-sucedida, `CommandBody`/`RawBody` são definidos como a transcrição para que os comandos de barra continuem funcionando.
* **Logs detalhados**: Em `--verbose`, registramos quando a transcrição é executada e quando ela substitui o corpo.

## Detecção automática (padrão)

Se você **não configurar modelos** e `tools.media.audio.enabled` **não** estiver definido como `false`,
o OpenClaw faz a detecção automática nesta ordem e para na primeira opção que funcionar:

1. **CLIs locais** (se instaladas)
   * `sherpa-onnx-offline` (requer `SHERPA_ONNX_MODEL_DIR` com encoder/decoder/joiner/tokens)
   * `whisper-cli` (de `whisper-cpp`; usa `WHISPER_CPP_MODEL` ou o modelo tiny incluído)
   * `whisper` (CLI em Python; baixa os modelos automaticamente)
2. **Gemini CLI** (`gemini`) usando `read_many_files`
3. **Chaves de provedor** (OpenAI → Groq → Deepgram → Google)

Para desativar a detecção automática, defina `tools.media.audio.enabled: false`.
Para personalizar, defina `tools.media.audio.models`.
Nota: A detecção de binários é best-effort em macOS/Linux/Windows; garanta que a CLI esteja em `PATH` (expandimos `~`), ou defina um modelo de CLI explícito com o caminho completo do comando.

## Exemplos de configuração

### Provedor + fallback de CLI (OpenAI + Whisper CLI)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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,
          },
        ],
      },
    },
  },
}
```

### Somente provedor com controle por escopo

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

### Somente provedor (Deepgram)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}
```

## Notas e limites

* A autenticação do provedor segue a ordem padrão de autenticação do modelo (perfis de autenticação, variáveis de ambiente, `models.providers.*.apiKey`).
* O Deepgram usa `DEEPGRAM_API_KEY` quando `provider: "deepgram"` é utilizado.
* Detalhes de configuração do Deepgram: [Deepgram (transcrição de áudio)](/providers/deepgram).
* Provedores de áudio podem sobrescrever `baseUrl`, `headers` e `providerOptions` via `tools.media.audio`.
* O limite de tamanho padrão é 20MB (`tools.media.audio.maxBytes`). Áudio acima do tamanho é ignorado para aquele modelo e a próxima entrada é tentada.
* O `maxChars` padrão para áudio é **não definido** (transcrição completa). Defina `tools.media.audio.maxChars` ou `maxChars` por entrada para reduzir a saída.
* O padrão automático da OpenAI é `gpt-4o-mini-transcribe`; defina `model: "gpt-4o-transcribe"` para maior precisão.
* Use `tools.media.audio.attachments` para processar várias notas de voz (`mode: "all"` + `maxAttachments`).
* A transcrição fica disponível para templates como `{{Transcript}}`.
* A saída stdout da CLI é limitada (5MB); mantenha a saída da CLI concisa.

## Detecção de menções em grupos

Quando `requireMention: true` está definido para um chat em grupo, o OpenClaw agora transcreve o áudio **antes** de verificar menções. Isso permite que mensagens de voz sejam processadas mesmo quando contêm menções.

**Como funciona:**

1. Se uma mensagem de voz não tiver texto e o grupo exigir menções, o OpenClaw realiza uma transcrição "preflight".
2. A transcrição é verificada em busca de padrões de menção (por exemplo, `@BotName`, gatilhos por emoji).
3. Se uma menção for encontrada, a mensagem segue pelo pipeline completo de resposta.
4. A transcrição é usada para detecção de menções para que mensagens de voz possam passar pela exigência de menção.

**Comportamento de fallback:**

* Se a transcrição falhar durante o preflight (timeout, erro de API, etc.), a mensagem será processada com base apenas na detecção de menção por texto.
* Isso garante que mensagens mistas (texto + áudio) nunca sejam descartadas incorretamente.

**Exemplo:** Um usuário envia uma mensagem de voz dizendo "Hey @Claude, what's the weather?" em um grupo do Telegram com `requireMention: true`. A mensagem de voz é transcrita, a menção é detectada e o agente responde.

## Pegadas

* As regras de escopo usam “primeira correspondência vence”. `chatType` é normalizado para `direct`, `group` ou `room`.
* Garanta que sua CLI finalize com código 0 e imprima texto simples; JSON precisa ser ajustado via `jq -r .text`.
* Mantenha timeouts razoáveis (`timeoutSeconds`, padrão 60s) para evitar bloquear a fila de respostas.
* A transcrição de preflight processa apenas o **primeiro** anexo de áudio para detecção de menção. Áudios adicionais são processados durante a fase principal de compreensão de mídia.