Tts on FixClaw

TTS Voice Note Delivery Regression in v2026.4.9

Fri, 10 Apr 2026 00:00:00 +0000

Symptom

After upgrading to OpenClaw v2026.4.9, TTS (text-to-speech) voice note delivery is completely broken:

Outbound TTS (Voice Notes from Assistant):

User sends a text message to the assistant via Telegram
Assistant calls tts tool with channel: "telegram"
Tool returns Generated audio reply
Expected: Voice note delivered to user
Actual: Only text response received; no voice note

Inbound STT (Voice Notes to Assistant):

User sends a voice note to the assistant via Telegram
Expected: Audio transcribed and processed
Actual: No transcription; pdf tool fails with “Expected PDF but got audio/ogg”, image tool fails with “Unsupported media type: audio”

Evidence from logs:

Gateway logs show no TTS-related events after the tts tool call
No sendVoice API calls are made to Telegram
Text messages continue to work correctly (proving Telegram connectivity is intact)

Historical logs show the last sendVoice attempts failing: telegram sendVoice failed: Network request for ‘sendVoice’ failed! telegram final reply failed: HttpError: Network request for ‘sendVoice’ failed!

Root Cause Analysis

The investigation reveals that the tool→channel delivery handoff is broken:

ElevenLabs API is functioning correctly — Audio files are successfully generated by the tts tool
Tool reports success — Generated audio reply message confirms audio creation
Broken handoff — The audio file is never passed to the gateway’s Telegram channel
No sendVoice call — No Telegram API call is initiated to deliver the voice note
Regression introduced in v2026.4.9 — The change from pre-v2026.4.9 behavior (corrupted delivery) to v2026.4.9 (no delivery) indicates a code regression in how the tts tool result is handled by the channel delivery layer

Pre-v2026.4.9 behavior: TTS generated audio but it was corrupted (appearing as long strings of exclamation marks in webchat).

v2026.4.9 behavior: TTS generates audio but delivers nothing at all.

The shift from “corrupted delivery” to “no delivery” suggests the audio file handling code path was either removed or broken during the v2026.4.9 update.

Solution

This is a code regression bug that requires a fix in the OpenClaw codebase. The following steps are needed:

Restore the sendVoice call path in the channel delivery layer — Ensure the audio file generated by the tts tool is properly passed to sendVoice for Telegram delivery
Verify audio file handling — Confirm the audio file path/content is correctly transferred between the tool result handler and the Telegram sender
Add integration tests for TTS→Telegram delivery to prevent future regressions
Fix STT handling — Ensure inbound voice notes are properly recognized and routed to the STT pipeline instead of being rejected as unsupported media types

Temporary Workaround:

Users may attempt to use the message tool with explicit media path for file attachment (untested)

Prevention

To prevent similar regressions in future releases:

Add automated TTS integration tests — Create end-to-end tests that verify voice notes are actually delivered to Telegram (not just that the tool reports success)
Test the full delivery pipeline — Ensure both generation AND delivery are tested together, not in isolation
Monitor channel delivery layer changes — Any modifications to how tool results are processed should include regression testing for media delivery
Log delivery confirmation — Add explicit logging when sendVoice is called to make failures more visible in logs
Multi-channel testing — Test TTS functionality when multiple channels (Telegram + webchat) are active simultaneously, as session handling issues may compound the problem

Additional Information

Affected versions: OpenClaw v2026.4.9 (updated 2026-04-09) and potentially later versions
Previous working behavior: Pre-v2026.4.9 had corrupted audio delivery
TTS Provider tested: ElevenLabs (eleven_multilingual_v2)
Channel: Telegram
Network connectivity: Confirmed working (text messages deliver successfully)
API credentials: ElevenLabs credentials verified functional via manual API calls
Multi-session factor: Session handling issues may contribute when Telegram and webchat are used simultaneously

Sources

GitHub Issue #64272

Agent-Sent TTS Audio Not Delivered via Webchat

Sun, 08 Mar 2026 00:00:00 +0000

Symptom

Agent-initiated TTS audio fails to reach webchat clients through two different paths:

Path 1: `tts` Tool

Agent calls the tts tool with text
textToSpeech() succeeds, audio file is created on disk (confirmed valid MP3)
Agent replies with NO_REPLY (as instructed by tool description)
No audio is delivered to the webchat client

Path 2: `[[tts]]` Tags

Agent includes [[tts]] or [[tts:text]]...[[/tts:text]] tags in a reply
During streaming, raw tags are visible in the UI (not processed)
After the run completes, no audio is delivered
Tags may remain visible as raw text in the final message

Working Path: `/tts audio`

User runs /tts audio Hello world
Audio is generated and delivered correctly on both webchat and Telegram

Root Cause Analysis

This is a regression caused by a mismatch between where audio is emitted and where it is processed in the reply delivery pipeline.

Root Cause 1: Block vs Final Payload Mismatch (`tts` tool path)

The issue lies in the disconnect between how pending tool media is emitted and how webchat processes replies:

Emission side (pi-embedded — handleAgentEnd → flushPendingMediaAndChannel): const pendingToolMediaReply = consumePendingToolMediaReply(ctx.state); if (pendingToolMediaReply && hasAssistantVisibleReply(pendingToolMediaReply)) ctx.emitBlockReply(pendingToolMediaReply); // ← emitted as “block” kind Audio is emitted as a “block” kind reply and queued in state.pendingToolMediaUrls.
Processing side (server.impl — webchat dispatch post-processing): const finalPayloads = deliveredReplies .filter((entry) => entry.kind === “final”) // ← blocks excluded .map((entry) => entry.payload); const audioBlocks = buildWebchatAudioContentBlocksFromReplyPayloads(finalPayloads); Webchat only extracts audio from “final” kind payloads, completely ignoring block payloads.

The block payload containing the audio file path is collected by the deliver callback but never processed for audio extraction. The audio file sits on disk, unused.

Root Cause 2: Auto-TTS Mode Skips Block Replies (`[[tts]]` tag path)

The auto-TTS mode defaults to "final", which causes block-kind replies to be skipped entirely:

// speech-core/runtime-api.js — maybeApplyTtsToPayload if ((config.mode ?? “final”) === “final” && params.kind && params.kind !== “final”) return nextPayload; // ← blocks skip TTS processing entirely

For streaming models, agent text is delivered incrementally as block replies, so [[tts]] tags pass through unprocessed during streaming.

A synthetic fallback exists in dispatch that attempts TTS on accumulated block text after the run completes:

// dispatch — after embedded run if (resolveConfiguredTtsMode(cfg) === “final” && replies.length === 0 && blockCount > 0 && accumulatedBlockText.trim()) { const ttsSyntheticReply = await maybeApplyTtsToReplyPayload({ payload: { text: accumulatedBlockText }, cfg, channel: ttsChannel, kind: “final”, … });

However, this fallback only fires when replies.length === 0 (no final replies returned from the embedded run). Whether the embedded run returns final replies depends on the model/provider implementation, making this path unreliable.

Solution

For `tts` tool path:

Modify server.impl to include block-kind payloads when extracting audio content blocks:

// server.impl — webchat dispatch post-processing // Before (broken): const finalPayloads = deliveredReplies .filter((entry) => entry.kind === “final”) .map((entry) => entry.payload);

// After (fixed): const allPayloads = deliveredReplies .map((entry) => entry.payload); const audioBlocks = buildWebchatAudioContentBlocksFromReplyPayloads(allPayloads);

For `[[tts]]` tag path:

Modify speech-core/runtime-api.js to process block-kind replies when in streaming mode:

// speech-core/runtime-api.js — maybeApplyTtsToPayload // Before (broken): if ((config.mode ?? “final”) === “final” && params.kind && params.kind !== “final”) return nextPayload;

// After (fixed): // Allow block-kind processing when streaming is active if (params.kind === “block” && !config.streamingMode) { return nextPayload; }

Alternatively, update the synthetic fallback in dispatch to be more robust regardless of whether final replies are present.

Prevention

Add integration tests that verify audio delivery for all TTS paths (tool, tags, and slash command) across all channels (webchat, Telegram).
Introduce a unified payload extraction function that processes both block and final kinds for audio content, preventing similar mismatches in the future.
Add QA checklist for TTS-related changes requiring verification that audio artifacts flow correctly from generation → emission → processing → delivery.
Document payload kind semantics clearly, especially the distinction between “block” and “final” kinds and which processing stages expect which kinds.

Additional Information

Affected version: 2026.3.7/2026.3.8
Operating system: Debian GNU/Linux 12 (bookworm)
Install method: Docker
Affected models: claude-opus-4.6, gpt-codex-5.4
Affected channels: web, telegram
Severity: Complete feature disablement (100% impact on agent-sent TTS)
Frequency: Always reproducible

The /tts audio slash command works correctly because it bypasses the embedded handler entirely and delivers audio through the standard final-payload path.

Sources

GitHub Issue #63033

Tts on FixClaw

TTS Voice Note Delivery Regression in v2026.4.9

Symptom

Root Cause Analysis

Solution

Prevention

Additional Information

Sources

Agent-Sent TTS Audio Not Delivered via Webchat

Symptom

Path 1: tts Tool

Path 2: [[tts]] Tags

Working Path: /tts audio

Root Cause Analysis

Root Cause 1: Block vs Final Payload Mismatch (tts tool path)

Root Cause 2: Auto-TTS Mode Skips Block Replies ([[tts]] tag path)

Solution

For tts tool path:

For [[tts]] tag path:

Prevention

Additional Information

Sources

Path 1: `tts` Tool

Path 2: `[[tts]]` Tags

Working Path: `/tts audio`

Root Cause 1: Block vs Final Payload Mismatch (`tts` tool path)

Root Cause 2: Auto-TTS Mode Skips Block Replies (`[[tts]]` tag path)

For `tts` tool path:

For `[[tts]]` tag path: