Zum Hauptinhalt springen

​
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)

{
  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

{
  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)

{
  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).
  • 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.