Audio / Sprachnachrichten — 17.01.2026

Was funktioniert

• Audio-Verständnis: Wenn Audio-Verständnis aktiviert ist (oder automatisch erkannt wird), macht OpenClaw Folgendes:
  1. Findet den ersten Audio-Anhang (lokaler Pfad oder URL) und lädt ihn bei Bedarf herunter.
  2. Prüft maxBytes vor dem Senden an jeden Model-Eintrag.
  3. Führt den ersten verfügbaren Model-Eintrag in der Reihenfolge aus (Provider oder CLI).
  4. Bei Fehler oder Überspringen (Größe/Timeout) wird der nächste Eintrag versucht.
  5. Bei Erfolg wird Body durch einen [Audio]-Block ersetzt und {{Transcript}} gesetzt.
• Command-Parsing: Wenn die Transkription erfolgreich ist, werden CommandBody/RawBody auf das Transkript gesetzt, sodass Slash-Commands weiterhin funktionieren.
• Verbose-Logging: Mit --verbose wird geloggt, wann die Transkription läuft und wann sie den Body ersetzt.

Auto-Erkennung (Standard)

Wenn du keine Models konfigurierst 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 (benötigt SHERPA_ONNX_MODEL_DIR mit encoder/decoder/joiner/tokens)
   • whisper-cli (von whisper-cpp; nutzt WHISPER_CPP_MODEL oder das mitgelieferte Tiny-Model)
   • whisper (Python-CLI; lädt Models automatisch herunter)
2. Gemini CLI (gemini) mit read_many_files
3. Provider-Keys (OpenAI → Groq → Deepgram → Google)

Um die Auto-Erkennung zu deaktivieren, setze tools.media.audio.enabled: false. Zum Anpassen setze tools.media.audio.models. Hinweis: Die Binary-Erkennung funktioniert best-effort unter macOS/Linux/Windows; stelle sicher, dass die CLI im PATH ist (wir expandieren ~), oder setze ein explizites CLI-Model mit vollständigem Command-Pfad.

Config-Beispiele

Provider + CLI-Fallback (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,
          },
        ],
      },
    },
  },
}

Nur Provider mit Scope-Gating

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

Nur Provider (Deepgram)

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

Hinweise & Limits

• Provider-Auth folgt der Standard-Model-Auth-Reihenfolge (Auth-Profile, Umgebungsvariablen, models.providers.*.apiKey).
• Deepgram nutzt DEEPGRAM_API_KEY, wenn provider: "deepgram" verwendet wird.
• Deepgram-Setup-Details: Deepgram (Audio-Transkription).
• Audio-Provider können baseUrl, headers und providerOptions über tools.media.audio überschreiben.
• Standard-Größenlimit ist 20 MB (tools.media.audio.maxBytes). Zu große Audio-Dateien werden für dieses Model übersprungen und der nächste Eintrag wird versucht.
• Standard-maxChars für Audio ist nicht gesetzt (vollständiges Transkript). Setze tools.media.audio.maxChars oder pro Eintrag maxChars, um die Ausgabe zu kürzen.
• OpenAI-Standard ist gpt-4o-mini-transcribe; setze model: "gpt-4o-transcribe" für höhere Genauigkeit.
• Nutze tools.media.audio.attachments, um mehrere Sprachnachrichten zu verarbeiten (mode: "all" + maxAttachments).
• Das Transkript ist für Templates als {{Transcript}} verfügbar.
• CLI-Stdout ist begrenzt (5 MB); halte die CLI-Ausgabe kompakt.

Stolperfallen

• Scope-Regeln nutzen First-Match-Wins. chatType wird normalisiert zu direct, group oder room.
• Stelle sicher, dass deine CLI mit Exit-Code 0 beendet und Plain-Text ausgibt; JSON muss über jq -r .text verarbeitet werden.
• Halte Timeouts vernünftig (timeoutSeconds, Standard 60s), um die Reply-Queue nicht zu blockieren.