Exclusive skill (only for companion/Mira) Version: 1.0.0
Feature Description
Call the ElevenLabs TTS API to synthesize text into speech, directly outputting ogg_opus format (no ffmpeg transcoding needed), sent via Telegram sendVoice interface. Supports natural switching between Chinese and English, and supportsvoice cloning—upload audio samples to configure a custom voice in the Lin Chi-ling style.
API Specifications
| Parameter | Value |
|---|---|
| Endpoint | https://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream |
| Model | eleven_multilingual_v2(best for mixed Chinese-English) / eleven_flash_v2_5(low latency) |
| Default voice | Built-in female voice (see recommended list below) |
| Output format | ogg_opus(natively supported, Telegram sendVoice can be used directly,no ffmpeg needed) |
| Maximum text length | 5,000 characters |
| Authentication method | xi-api-key: {ELEVENLABS_API_KEY} |
Recommended Voice Options
Built-in voices (available with zero configuration)
| Voice name | Style | Chinese performance | Use case |
|---|---|---|---|
Sarah |
Gentle, warm | Good | Mira emotional companionship (recommended starting point) |
Rachel |
Steady, intellectual | Good | evening / weekly quiet messages |
Aria |
Clear, neutral | Good | Daily conversation |
Built-in voices are all native English speakers; when handling Chinese via
eleven_multilingual_v2there is a slight foreign accent, suitable for use when users accept this style.
Voice cloning (recommended for natural pure Chinese pronunciation)
Clone a voice via ElevenLabs Voice Lab to achieve natural Chinese pronunciation close to the Lin Chi-ling style:
1. 登录 ElevenLabs → Voice Lab → Add Voice → Instant Voice Cloning
2. 上传 1-5 分钟高质量中文音频(清晰、少背景噪声、情感自然)
3. 命名声音(如 "Mira_ZH"),完成克隆后获取 Voice ID
4. 将 Voice ID 填入 ~/.openclaw/.env.local 的 ELEVENLABS_VOICE_ID 字段
The quality of the cloned voice depends on the sample audio quality: clear, emotionally rich, and over 1 minute works best.
Calling the Interface
speak(text, voice_id=None, output_path=None) → str
输入:
text 必填,要合成的文字
voice_id 可选,覆盖 ELEVENLABS_VOICE_ID 环境变量配置
output_path 可选,指定输出路径(默认 /tmp/mira_tts_{uuid}.ogg)
输出:
str — 生成的 ogg 文件绝对路径
异常:
ElevenLabsTTSError — API 调用失败(含 HTTP 状态码)
QuotaExceededError — 月度字符额度耗尽(HTTP 429)
Synthesis Workflow
1. 读取 ELEVENLABS_VOICE_ID(未配置则使用内置 Sarah voice ID)
2. POST /v1/text-to-speech/{voice_id}/stream:
Headers:
xi-api-key: {ELEVENLABS_API_KEY}
Accept: audio/ogg; codecs=opus
Content-Type: application/json
Body:
{
"text": "<消息文字>",
"model_id": "eleven_multilingual_v2",
"voice_settings": {
"stability": 0.65,
"similarity_boost": 0.80,
"style": 0.35,
"use_speaker_boost": true
}
}
3. 流式接收 ogg_opus 数据,写入 /tmp/mira_tts_{uuid}.ogg
4. 返回 .ogg 文件路径
Parameter Description:
stability: 0.65— retains emotional flexibility, not too mechanical;style: 0.35— slightly stylized, natural without being exaggerated. Can be fine-tuned in thevoice_stylefield of USER.md.
Integration with Telegram
After generating the .ogg file, send via sendVoice :
POST https://api.telegram.org/bot{TG_BOT_TOKEN_COMPANION}/sendVoice
Content-Type: multipart/form-data
chat_id: <TG_ADMIN_CHAT_ID>
voice: <.ogg 文件>
caption: <原始文字>(可选,作为字幕)
Delete the temporary .ogg file immediately after sending.
Usage Tracking
ElevenLabs bills by character; record usage after each call:
// ~/.openclaw/workspaces/companion/logs/elevenlabs-usage.json
{
"month": "2026-02",
"totalChars": 12450,
"limitChars": 30000,
"remaining": 17550,
"lastUpdated": "2026-02-25T10:30:00Z"
}
When the remaining quota falls below 10%, automatically downgrade to text sending and notify the user via Telegram to check usage.
Text Preprocessing Rules
| Item | Rule |
|---|---|
| Markdown symbols | Remove **、_、~、` and other formatting symbols |
| URL | Replace with "a link" |
| Emoji | Keep (multilingual v2 will handle naturally) |
| Oversized messages | When > 500 characters, truncate to the first 500 characters; also send the full text version |
Voice Sending Timing
Same as minimax-tts, the trigger logic is controlled by the proactive-chat skill:
| Trigger type | Default behavior | Reason |
|---|---|---|
morning |
Voice-first | Morning greetings are good for listening |
evening |
Voice-first | Stronger sense of companionship at night |
weekly |
Voice-first | Emotional reviews are good for conveying through voice |
discovery |
Text-first | Content containing links/quotes is not suitable for reading aloud |
| Direct user dialogue | Text (unless the user requests otherwise) | Dialogue reply efficiency takes priority |
Users can, in USER.md 's voice_messages field, disable voice (enabled: false) or adjust voice_style(stability/similarity parameters).
Fallback strategy
| Condition | Handling |
|---|---|
ELEVENLABS_API_KEY is not configured |
Fall back to text, record a warn log |
| HTTP 4xx / 5xx | Fall back, record an error log |
| Monthly quota exhausted (HTTP 429) | Fall back, notify the user to top up |
| Remaining balance < 10% | Automatically fall back, notify the user |
| Text < 5 characters | Fall back |
USER.md voice_messages.enabled: false |
Fall back |
| Discovery message contains an external link | Fall back |
Environment variable
| Variable | Required | Description |
|---|---|---|
ELEVENLABS_API_KEY |
✅ | ElevenLabs platform API Key (elevenlabs.io) |
ELEVENLABS_VOICE_ID |
Optional | Custom/cloned voice ID (if not configured, the built-in Sarah is used) |
Dependencies
requests(Python HTTP request)- No ffmpeg needed (native ogg_opus output)
ELEVENLABS_API_KEYTG_BOT_TOKEN_COMPANION、TG_ADMIN_CHAT_ID
Logs
- Synthesis successful:
~/.openclaw/workspaces/companion/logs/tts.log(records voice_id, character count, elapsed time) - Usage tracking:
~/.openclaw/workspaces/companion/logs/elevenlabs-usage.json - Fallback records:
tts.log(including the fallback reason) - Errors:
~/.openclaw/workspaces/companion/logs/error.log
Comparison with minimax-tts
| Dimension | elevenlabs-tts | minimax-tts |
|---|---|---|
| Chinese naturalness | ⭐⭐⭐⭐ Good (multilingual v2) | ⭐⭐⭐⭐⭐ Excellent (native Chinese) |
| Mixed Chinese and English | ⭐⭐⭐⭐⭐ Excellent | ⭐⭐⭐⭐ Good |
| ogg output | ✅ Natively supported, no ffmpeg needed | ❌ Requires ffmpeg transcoding |
| Voice cloning | ✅ Supported (Instant Cloning) | ❌ Not supported |
| Latency | ~600–1200ms | ~300–600ms |
| Cost | Medium (Starter $5/30K characters) | Low (more cost-effective for Chinese scenarios) |
| Recommended scenarios | Voice cloning, mixed Chinese and English messages | Pure Chinese, low latency, low cost |