Audio / Sprachnachrichten — 2026-01-17

Was funktioniert

  • Media Understanding (Audio): Wenn Audio-Verständnis aktiviert (oder automatisch erkannt) ist, 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 Modelleintrag.
    3. Führt den ersten passenden Modelleintrag der Reihe nach aus (Provider oder CLI).
    4. Falls dieser fehlschlägt oder übersprungen wird (Größe/Timeout), wird der nächste Eintrag versucht.
    5. Bei Erfolg wird Body durch einen [Audio]-Block ersetzt und {{Transcript}} gesetzt.
  • Befehlserkennung: Wenn die Transkription erfolgreich ist, werden CommandBody/RawBody auf das Transkript gesetzt, sodass Slash-Befehle weiterhin funktionieren.
  • Ausführliches Logging: Im --verbose-Modus wird protokolliert, wann die Transkription läuft und wann sie den Body ersetzt.

Automatische Erkennung (Standard)

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

Um die automatische Erkennung zu deaktivieren, setze tools.media.audio.enabled: false. Zum Anpassen setze tools.media.audio.models. Hinweis: Die Binärerkennung funktioniert plattformübergreifend (macOS/Linux/Windows) nach bestem Bemühen. Stelle sicher, dass die CLI im PATH liegt (wir expandieren ~), oder setze ein explizites CLI-Modell mit vollem Befehlspfad.

Konfigurationsbeispiele

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

Nur Provider (Mistral Voxtral)

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

Transkript an Chat zurücksenden (Opt-in)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // Standard ist false
        echoFormat: '📝 "{transcript}"', // optional, unterstützt {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Hinweise und Limits

  • Provider-Authentifizierung folgt der Standard-Reihenfolge (Auth-Profile, Umgebungsvariablen, models.providers.*.apiKey).
  • Deepgram nutzt DEEPGRAM_API_KEY, wenn provider: "deepgram" verwendet wird.
  • Deepgram-Einrichtungsdetails: Deepgram (Audio-Transkription).
  • Mistral-Einrichtungsdetails: Mistral.
  • 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 Audiodateien werden für dieses Modell übersprungen und der nächste Eintrag wird versucht.
  • Winzige/leere Audiodateien unter 1024 Bytes werden vor der Provider/CLI-Transkription übersprungen.
  • Standard maxChars für Audio ist nicht gesetzt (volles Transkript). Setze tools.media.audio.maxChars oder pro Eintrag maxChars, um die Ausgabe zu kürzen.
  • OpenAI-Auto-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 in Templates als {{Transcript}} verfügbar.
  • tools.media.audio.echoTranscript ist standardmäßig aus; aktiviere es, um eine Transkript-Bestätigung vor der Agent-Verarbeitung an den Ursprungs-Chat zurückzusenden.
  • tools.media.audio.echoFormat passt den Echo-Text an (Platzhalter: {transcript}).
  • CLI-Stdout ist begrenzt (5 MB); halte die CLI-Ausgabe knapp.

Proxy-Unterstützung

Provider-basierte Audio-Transkription berücksichtigt die üblichen Proxy-Umgebungsvariablen für ausgehende Verbindungen:

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

Wenn keine Proxy-Variablen gesetzt sind, wird eine direkte Verbindung verwendet. Bei fehlerhafter Proxy-Konfiguration loggt OpenClaw eine Warnung und fällt auf direkten Zugriff zurück.

Mention-Erkennung in Gruppen

Wenn requireMention: true für einen Gruppenchat gesetzt ist, transkribiert OpenClaw Audio jetzt vor der Mention-Prüfung. So können Sprachnachrichten auch verarbeitet werden, wenn sie Mentions enthalten.

So funktioniert es:

  1. Wenn eine Sprachnachricht keinen Textbody hat und die Gruppe Mentions erfordert, führt OpenClaw eine „Preflight”-Transkription durch.
  2. Das Transkript wird auf Mention-Muster geprüft (z. B. @BotName, Emoji-Trigger).
  3. Wird ein Mention gefunden, durchläuft die Nachricht die vollständige Antwort-Pipeline.
  4. Das Transkript wird für die Mention-Erkennung verwendet, damit Sprachnachrichten die Mention-Prüfung bestehen können.

Fallback-Verhalten:

  • Wenn die Transkription beim Preflight fehlschlägt (Timeout, API-Fehler usw.), wird die Nachricht nur anhand der Text-Mention-Erkennung verarbeitet.
  • So wird sichergestellt, dass gemischte Nachrichten (Text + Audio) nie fälschlicherweise verworfen werden.

Opt-out pro Telegram-Gruppe/Topic:

  • Setze channels.telegram.groups.<chatId>.disableAudioPreflight: true, um die Preflight-Transkriptions-Mention-Prüfung für diese Gruppe zu überspringen.
  • Setze channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight, um pro Topic zu überschreiben (true zum Überspringen, false zum Erzwingen).
  • Standard ist false (Preflight aktiviert, wenn Mention-Bedingungen zutreffen).

Beispiel: Ein Nutzer sendet eine Sprachnachricht mit „Hey @Claude, wie ist das Wetter?” in einer Telegram-Gruppe mit requireMention: true. Die Sprachnachricht wird transkribiert, der Mention erkannt und der Agent antwortet.

Stolperfallen

  • Scope-Regeln verwenden First-Match-Wins. chatType wird auf direct, group oder room normalisiert.
  • Stelle sicher, dass dein CLI mit Exit-Code 0 beendet und Klartext ausgibt; JSON muss über jq -r .text aufbereitet werden.
  • Bei parakeet-mlx: Wenn du --output-dir übergibst, liest OpenClaw <output-dir>/<media-basename>.txt, wenn --output-format txt ist (oder weggelassen wird); andere Ausgabeformate fallen auf Stdout-Parsing zurück.
  • Halte Timeouts vernünftig (timeoutSeconds, Standard 60s), um die Antwort-Queue nicht zu blockieren.
  • Preflight-Transkription verarbeitet nur den ersten Audio-Anhang für die Mention-Erkennung. Weitere Audiodateien werden in der Hauptphase des Media Understanding verarbeitet.
arrow_back
Zurück
Images
Weiter
Camera
arrow_forward