> ## 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.

# Audio- und Sprachnachrichten

# Audio / Sprachnachrichten — 2026-01-17

## Was funktioniert

* **Medienverständnis (Audio)**: Wenn Audioverständnis aktiviert ist (oder automatisch erkannt wird), führt OpenClaw Folgendes aus:
  1. Sucht den ersten Audio‑Anhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter.
  2. Erzwingt `maxBytes` vor dem Senden an jeden Modelleinsatz.
  3. Führt den ersten geeigneten Modelleinsatz der Reihe nach aus (Anbieter oder CLI).
  4. Bei Fehlschlag oder Überspringen (Größe/Timeout) wird der nächste Eintrag versucht.
  5. Bei Erfolg wird `Body` durch einen `[Audio]`‑Block ersetzt und `{{Transcript}}` gesetzt.
* **Befehlsparsing**: Wenn die Transkription erfolgreich ist, werden `CommandBody`/`RawBody` auf das Transkript gesetzt, sodass Slash‑Befehle weiterhin funktionieren.
* **Ausführliches Logging**: In `--verbose` protokollieren wir, wann die Transkription ausgeführt wird und wann sie den Text ersetzt.

## Automatische Erkennung (Standard)

Wenn Sie **keine Modelle konfigurieren** und `tools.media.audio.enabled` **nicht** auf `false` gesetzt ist,
erkennt OpenClaw automatisch in dieser Reihenfolge und stoppt bei der ersten funktionierenden Option:

1. **Lokale CLIs** (falls installiert)
   * `sherpa-onnx-offline` (erfordert `SHERPA_ONNX_MODEL_DIR` mit Encoder/Decoder/Joiner/Tokens)
   * `whisper-cli` (aus `whisper-cpp`; verwendet `WHISPER_CPP_MODEL` oder das gebündelte Tiny‑Modell)
   * `whisper` (Python‑CLI; lädt Modelle automatisch herunter)
2. **Gemini‑CLI** (`gemini`) unter Verwendung von `read_many_files`
3. **Anbieter‑Schlüssel** (OpenAI → Groq → Deepgram → Google)

Um die automatische Erkennung zu deaktivieren, setzen Sie `tools.media.audio.enabled: false`.
Zur Anpassung setzen Sie `tools.media.audio.models`.
Hinweis: Die Erkennung von Binärdateien ist bestmöglich über macOS/Linux/Windows hinweg; stellen Sie sicher, dass die CLI auf `PATH` liegt (wir erweitern `~`), oder setzen Sie ein explizites CLI‑Modell mit vollständigem Befehlspfad.

## Konfigurationsbeispiele

### Anbieter + CLI‑Fallback (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,
          },
        ],
      },
    },
  },
}
```

### Nur Anbieter mit Scope‑Gating

```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" }],
      },
    },
  },
}
```

### Nur Anbieter (Deepgram)

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

## Hinweise & Limits

* Die Anbieter‑Authentifizierung folgt der Standardreihenfolge der Modell‑Authentifizierung (Auth‑Profile, Umgebungsvariablen, `models.providers.*.apiKey`).
* Deepgram übernimmt `DEEPGRAM_API_KEY`, wenn `provider: "deepgram"` verwendet wird.
* Details zur Deepgram‑Einrichtung: [Deepgram (Audiotranskription)](/providers/deepgram).
* Audioanbieter können `baseUrl`, `headers` und `providerOptions` über `tools.media.audio` überschreiben.
* Das Standard‑Größenlimit beträgt 20 MB (`tools.media.audio.maxBytes`). Übergroße Audiodateien werden für dieses Modell übersprungen und der nächste Eintrag wird versucht.
* Der Standardwert für `maxChars` bei Audio ist **nicht gesetzt** (vollständiges Transkript). Setzen Sie `tools.media.audio.maxChars` oder pro Eintrag `maxChars`, um die Ausgabe zu kürzen.
* Der OpenAI‑Standard ist automatisch `gpt-4o-mini-transcribe`; setzen Sie `model: "gpt-4o-transcribe"` für höhere Genauigkeit.
* Verwenden Sie `tools.media.audio.attachments`, um mehrere Sprachnachrichten zu verarbeiten (`mode: "all"` + `maxAttachments`).
* Das Transkript steht Templates als `{{Transcript}}` zur Verfügung.
* CLI‑stdout ist begrenzt (5 MB); halten Sie die CLI‑Ausgabe knapp.

## Erwähnungserkennung in Gruppen

Wenn `requireMention: true` für einen Gruppenchat gesetzt ist, transkribiert OpenClaw nun Audio **vor** der Überprüfung auf Erwähnungen. Dadurch können Sprachnachrichten verarbeitet werden, auch wenn sie Erwähnungen enthalten.

**So funktioniert es:**

1. Wenn eine Sprachnachricht keinen Textinhalt hat und die Gruppe Erwähnungen erfordert, führt OpenClaw eine „Preflight“-Transkription durch.
2. Das Transkript wird auf Erwähnungsmuster geprüft (z. B. `@BotName`, Emoji-Trigger).
3. Wird eine Erwähnung gefunden, durchläuft die Nachricht die vollständige Antwort-Pipeline.
4. Das Transkript wird für die Erwähnungserkennung verwendet, sodass Sprachnachrichten die Erwähnungsprüfung bestehen können.

**Fallback-Verhalten:**

* Wenn die Transkription während des Preflight-Vorgangs fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht basierend auf einer reinen Text-Erwähnungserkennung verarbeitet.
* Dadurch wird sichergestellt, dass gemischte Nachrichten (Text + Audio) niemals fälschlicherweise verworfen werden.

**Beispiel:** Ein Benutzer sendet in einer Telegram-Gruppe mit `requireMention: true` eine Sprachnachricht mit dem Inhalt „Hey @Claude, wie ist das Wetter?“. Die Sprachnachricht wird transkribiert, die Erwähnung wird erkannt, und der Agent antwortet.

## Gotchas

* Scope‑Regeln verwenden „First‑Match‑Wins“. `chatType` wird zu `direct`, `group` oder `room` normalisiert.
* Stellen Sie sicher, dass Ihre CLI mit Exit‑Code 0 beendet wird und reinen Text ausgibt; JSON muss über `jq -r .text` aufbereitet werden.
* Halten Sie Timeouts angemessen (`timeoutSeconds`, Standard 60 s), um das Blockieren der Antwort‑Warteschlange zu vermeiden.
* Die Preflight-Transkription verarbeitet nur den **ersten** Audio-Anhang für die Erwähnungserkennung. Zusätzliche Audiodateien werden während der Hauptphase der Medienverarbeitung verarbeitet.