Voice & Text-to-Speech Setup

Fix MEDIA: Path Appearing as Text

When you see output like:

🦞 Got it. MEDIA: /Users/you/.openclaw/cache/tts/abc123.ogg

Instead of receiving an actual voice note, try these fixes:

1. Verify TTS Configuration

Check your current TTS settings:

You should see something like:

{  "provider": "elevenlabs",  "auto": "always",  "elevenlabs": {    "voiceId": "FF7KdobWPaiR0vkcALHF",    "modelId": "eleven_v3"  }}

2. Ensure Provider API Key is Set

ElevenLabs requires a valid API key:

Get your API key from: https://elevenlabs.io/app/settings/api-keys

3. Restart the Gateway

After any TTS configuration change, restart:

4. Check Channel Voice Capability

Not all channels support voice notes the same way. Verify your channel:

• Telegram: Full voice note support via asVoice: true
• Discord: Voice attachments work as audio files
• Slack/iMessage: May render as file attachments

5. Test TTS Directly

Ask the agent explicitly to speak:

Say "hello world" as a voice note

Or use the /tts command if available:

/tts Hello, this is a test

6. Check for Model Instruction Issues

Some models may not properly handle TTS tool calls. If using a non-Anthropic model (like Kimi K2.5), ensure it understands the TTS tool schema. You may need to add explicit instructions in your IDENTITY.md:

## Voice OutputWhen TTS is enabled, use the tts tool to convert responses to speech.Do not output MEDIA: paths as text - the system handles audio attachment automatically.

Hands-Free Voice-Only Setup (Car/Bluetooth)

For safe driving use with Bluetooth, configure full voice loop:

1. Enable Always-On TTS

Make the agent always respond with voice:

2. Configure Speech-to-Text (STT)

Enable STT so you can speak instead of typing:

Alternative STT providers:

• whisper - OpenAI Whisper (local or API)
• deepgram - Fast and accurate
• google - Google Cloud Speech

3. Telegram Voice Message Workflow

For Telegram, the safest hands-free flow:

1. Send voice messages - Telegram converts your speech to a voice note
2. OpenClaw transcribes - STT converts your voice to text
3. Agent processes - Responds to your request
4. TTS converts - Response becomes a voice note
5. Bluetooth plays - You hear the response through car speakers

4. iOS Shortcuts Integration (Advanced)

Create an iOS Shortcut for truly hands-free activation:

1. Create a Shortcut that sends a message to your Telegram bot
2. Use "Hey Siri" to trigger the shortcut
3. Dictate your message
4. The agent responds via voice note

Example Shortcut actions:

• Get input from Spoken Text
• Send message to Telegram chat
• Wait for response
• Play audio

5. Safety Configuration

For driving, add guardrails in your IDENTITY.md:

## Driving ModeKeep responses brief and clear for audio playback.No visual elements (tables, code blocks) - voice-friendly only.Confirm critical actions verbally before executing.