Teks-ke-ucapan

OpenClaw mengonversi balasan keluar menjadi audio melalui 14 penyedia ucapan: pesan suara native di Feishu, Matrix, Telegram, dan WhatsApp; lampiran audio di tempat lain; serta stream PCM/Ulaw untuk telefoni dan Talk.

TTS adalah bagian keluaran ucapan dari mode stt-tts Talk (talk.speak menggunakan jalur sintesis yang sama). Sesi Talk realtime yang native dari penyedia menyintesis ucapan di dalam penyedia waktu nyata; sesi transcription tidak pernah menyintesis balasan suara asisten.

Mulai cepat

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",    },  },}

Penyedia yang didukung

Jika beberapa penyedia dikonfigurasi, penyedia yang dipilih digunakan terlebih dahulu dan penyedia lainnya menjadi opsi fallback. Ringkasan otomatis menggunakan summaryModel (atau agents.defaults.model.primary), sehingga penyedia tersebut juga harus diautentikasi jika ringkasan tetap diaktifkan.

Konfigurasi

Konfigurasi TTS berada di bawah messages.tts dalam ~/.openclaw/openclaw.json. Pilih preset dan sesuaikan blok penyedia. Kolom speakerVoice/speakerVoiceId yang ditampilkan di bawah bersifat kanonis; nama kolom voice/voiceId/ voiceName milik setiap penyedia tetap berfungsi sebagai alias lama.

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      speakerVoice: "en-US-JennyNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "elevenlabs",  providers: {    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      speakerVoice: "Kore",      // Perintah gaya bahasa alami opsional:      // audioProfile: "Bicaralah dengan nada tenang seperti pembawa acara podcast.",      // speakerName: "Alex",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "gradium",  providers: {    gradium: {      apiKey: "${GRADIUM_API_KEY}",      speakerVoiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      speakerVoiceId: "Sarah",      temperature: 0.7,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "tts-local-cli",  providers: {    "tts-local-cli": {      command: "say",      args: ["-o", "{{OutputPath}}", "{{Text}}"],      outputFormat: "wav",      timeoutMs: 120000,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "microsoft",  providers: {    microsoft: {      enabled: true,      speakerVoice: "en-US-MichelleNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      rate: "+0%",      pitch: "+0%",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "minimax",  providers: {    minimax: {      apiKey: "${MINIMAX_API_KEY}",      model: "speech-2.8-hd",      speakerVoiceId: "English_expressive_narrator",      speed: 1.0,      vol: 1.0,      pitch: 0,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "openai",  summaryModel: "openai/gpt-4.1-mini",  modelOverrides: { enabled: true },  providers: {    openai: {      apiKey: "${OPENAI_API_KEY}",      model: "gpt-4o-mini-tts",      speakerVoice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",      voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },      applyTextNormalization: "auto",      languageCode: "en",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "openrouter",  providers: {    openrouter: {      apiKey: "${OPENROUTER_API_KEY}",      model: "hexgrad/kokoro-82m",      speakerVoice: "af_alloy",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "volcengine",  providers: {    volcengine: {      apiKey: "${VOLCENGINE_TTS_API_KEY}",      resourceId: "seed-tts-1.0",      speakerVoice: "en_female_anna_mars_bigtts",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xai",  providers: {    xai: {      apiKey: "${XAI_API_KEY}",      speakerVoiceId: "eve",      language: "en",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xiaomi",  providers: {    xiaomi: {      apiKey: "${XIAOMI_API_KEY}",      model: "mimo-v2.5-tts",      speakerVoice: "mimo_default",      format: "mp3",    },  },},},}

Untuk Xiaomi mimo-v2.5-tts-voicedesign, hilangkan speakerVoice dan atur style menjadi perintah desain suara. OpenClaw mengirim perintah tersebut sebagai pesan TTS user dan tidak mengirim audio.voice untuk model voicedesign.

Penggantian suara per agen

Gunakan agents.list[].tts ketika satu agen harus berbicara dengan penyedia, suara, model, persona, atau mode TTS otomatis yang berbeda. Blok agen digabungkan secara mendalam di atas messages.tts, sehingga kredensial penyedia dapat tetap berada dalam konfigurasi penyedia global:

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",      providers: {        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },      },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Untuk menetapkan persona per agen, atur agents.list[].tts.persona bersama konfigurasi penyedia — pengaturan ini menggantikan messages.tts.persona global hanya untuk agen tersebut.

Urutan prioritas untuk balasan otomatis, /tts audio, /tts status, dan alat agen tts:

1. messages.tts
2. agents.list[].tts aktif
3. penggantian saluran, ketika saluran mendukung channels.<channel>.tts
4. penggantian akun, ketika saluran meneruskan channels.<channel>.accounts.<id>.tts
5. preferensi /tts lokal untuk host ini
6. direktif [[tts:...]] sebaris ketika penggantian model diaktifkan

Penggantian saluran dan akun menggunakan bentuk yang sama dengan messages.tts dan digabungkan secara mendalam di atas lapisan sebelumnya, sehingga kredensial penyedia bersama dapat tetap berada di messages.tts, sementara saluran atau akun bot hanya mengubah suara pembicara, model, persona, atau mode otomatis:

{  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Persona

Persona adalah identitas suara stabil yang dapat diterapkan secara deterministik di berbagai penyedia. Persona dapat memprioritaskan satu penyedia, menentukan maksud prompt yang netral terhadap penyedia, dan membawa pengikatan khusus penyedia untuk suara, model, templat prompt, seed, dan pengaturan suara.

Persona minimal

{  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Narator",          provider: "elevenlabs",          providers: {            elevenlabs: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

Persona lengkap (prompt netral terhadap penyedia)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Narator kepala pelayan Inggris yang tenang, hangat, dan jenaka.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Kepala pelayan Inggris yang cerdas. Tenang, jenaka, hangat, menawan, ekspresif secara emosional, dan tidak pernah generik.",            scene: "Ruang kerja yang tenang pada larut malam. Narasi dengan mikrofon dekat untuk operator tepercaya.",            sampleContext: "Pembicara menjawab permintaan teknis pribadi dengan keyakinan yang ringkas dan kehangatan yang jenaka.",            style: "Berkelas, bersahaja, sedikit geli.",            accent: "Bahasa Inggris Britania.",            pacing: "Terukur, dengan jeda dramatis singkat.",            constraints: ["Jangan bacakan nilai konfigurasi.", "Jangan jelaskan persona."],          },          providers: {            google: {              model: "gemini-3.1-flash-tts-preview",              speakerVoice: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },            elevenlabs: {              speakerVoiceId: "voice_id",              modelId: "eleven_multilingual_v2",              seed: 42,              voiceSettings: {                stability: 0.65,                similarityBoost: 0.8,                style: 0.25,                useSpeakerBoost: true,                speed: 0.95,              },            },          },        },      },    },  },}

Resolusi persona

Persona aktif dipilih secara deterministik:

1. Preferensi lokal /tts persona <id>, jika diatur.
2. messages.tts.persona, jika diatur.
3. Tanpa persona.

Pemilihan penyedia mendahulukan pengaturan eksplisit:

1. Penggantian langsung (CLI, Gateway, Talk, direktif TTS yang diizinkan).
2. Preferensi lokal /tts provider <id>.
3. provider milik persona aktif.
4. messages.tts.provider.
5. Pemilihan otomatis dari registri.

Untuk setiap percobaan penyedia, OpenClaw menggabungkan konfigurasi dalam urutan berikut:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Penggantian permintaan tepercaya
4. Penggantian direktif TTS yang dihasilkan model dan diizinkan

Cara penyedia menggunakan prompt persona

Bidang prompt persona (profile, scene, sampleContext, style, accent, pacing, constraints) bersifat netral terhadap penyedia. Setiap penyedia menentukan cara menggunakannya:

Kebijakan fallback

fallbackPolicy mengontrol perilaku ketika persona tidak memiliki pengikatan untuk penyedia yang dicoba:

Seluruh permintaan TTS hanya gagal ketika setiap penyedia yang dicoba dilewati atau gagal.

Pemilihan penyedia sesi Talk memiliki cakupan sesi. Klien Talk harus memilih ID penyedia, ID model, ID suara, dan lokal dari talk.catalog, lalu meneruskannya melalui permintaan sesi atau serah terima Talk. Membuka sesi suara tidak boleh mengubah messages.tts atau default penyedia Talk global.

Direktif yang digerakkan model

Secara default, asisten dapat menghasilkan direktif [[tts:...]] untuk mengganti suara, model, atau kecepatan untuk satu balasan, ditambah blok opsional [[tts:text]]...[[/tts:text]] untuk isyarat ekspresif yang hanya boleh muncul dalam audio:

Ini dia. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](tertawa) Bacakan lagu itu sekali lagi.[[/tts:text]]

Ketika messages.tts.auto adalah "tagged", direktif diwajibkan untuk memicu audio. Pengiriman blok streaming menghapus direktif dari teks yang terlihat sebelum saluran menerimanya, bahkan ketika direktif terbagi di antara blok yang berdekatan.

provider=... diabaikan kecuali modelOverrides.allowProvider: true. Ketika sebuah balasan mendeklarasikan provider=..., kunci lain dalam direktif tersebut diurai hanya oleh penyedia itu; kunci yang tidak didukung dihapus dan dilaporkan sebagai peringatan direktif TTS.

Kunci direktif yang tersedia:

• provider (ID penyedia terdaftar; memerlukan allowProvider: true)
• speakerVoice / speakerVoiceId (alias lama: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, (0, 10])
• pitch (nada bilangan bulat MiniMax, −12 hingga 12; nilai pecahan dipotong)
• emotion (tag emosi Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Nonaktifkan penggantian model sepenuhnya:

{ messages: { tts: { modelOverrides: { enabled: false } } } }

Izinkan peralihan penyedia sambil mempertahankan konfigurabilitas pengaturan lain:

{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }

Perintah garis miring

Perintah tunggal /tts. Di Discord, OpenClaw juga mendaftarkan /voice karena /tts adalah perintah bawaan Discord — teks /tts ... tetap berfungsi.

/tts off | on | status/tts chat on | off | default/tts latest/tts provider <id>/tts persona <id> | off/tts limit <chars>/tts summary off/tts audio <text>

Catatan perilaku:

• /tts on menulis preferensi TTS lokal ke always; /tts off menulisnya ke off.
• /tts chat on|off|default menulis penggantian TTS otomatis dengan cakupan sesi untuk percakapan saat ini.
• /tts persona <id> menulis preferensi persona lokal; /tts persona off menghapusnya.
• /tts latest membaca balasan asisten terbaru dari transkrip sesi saat ini dan mengirimkannya satu kali sebagai audio. Perintah ini hanya menyimpan hash balasan tersebut pada entri sesi untuk mencegah pengiriman suara duplikat.
• /tts audio menghasilkan balasan audio satu kali (dan tidak mengaktifkan TTS).
• /tts limit <chars> menerima 100–4096 (4096 adalah batas maksimum keterangan/pesan Telegram); nilai di luar rentang tersebut ditolak.
• limit dan summary disimpan dalam preferensi lokal, bukan konfigurasi utama.
• /tts status menyertakan diagnostik fallback untuk percobaan terbaru — Fallback: <primary> -> <used>, Attempts: ..., dan detail per percobaan (provider:outcome(reasonCode) latency).
• /status menampilkan mode TTS aktif beserta penyedia, model, suara, dan metadata titik akhir khusus yang telah disanitasi saat TTS diaktifkan.

Preferensi per pengguna

Perintah garis miring menulis penggantian lokal ke prefsPath. Default-nya adalah ~/.openclaw/settings/tts.json; ganti dengan variabel lingkungan OPENCLAW_TTS_PREFS atau messages.tts.prefsPath.

Ini menggantikan konfigurasi efektif dari messages.tts beserta blok agents.list[].tts aktif untuk host tersebut.

Format keluaran

Pengiriman suara TTS ditentukan oleh kemampuan kanal. Plugin kanal mengiklankan apakah TTS bergaya suara harus meminta target voice-note native dari penyedia atau mempertahankan sintesis audio-file normal, serta apakah kanal mentranskode keluaran non-native sebelum mengirimkannya.

Catatan per penyedia:

• Transkode Feishu / WhatsApp: ketika balasan pesan suara diterima sebagai MP3/WebM/WAV/M4A atau berkas audio lain yang mungkin, Plugin kanal mentranskodenya menjadi Ogg/Opus 48 kHz dengan ffmpeg (libopus, 64 kbps) sebelum mengirim pesan suara native. WhatsApp mengirim hasilnya melalui payload audio Baileys dengan ptt: true dan audio/ogg; codecs=opus. Jika transkode gagal: Feishu menangkap galat dan kembali mengirimkan berkas asli sebagai lampiran biasa; WhatsApp tidak memiliki fallback, sehingga pengiriman itu sendiri gagal alih-alih memposting payload PTT yang tidak kompatibel.
• MiniMax: MP3 (model speech-2.8-hd, laju sampel 32 kHz) untuk lampiran audio normal; ditranskode menjadi Opus 48 kHz dengan ffmpeg untuk target pesan suara yang diiklankan kanal.
• Xiaomi MiMo: MP3 secara bawaan, atau WAV jika dikonfigurasi; ditranskode menjadi Opus 48 kHz dengan ffmpeg untuk target pesan suara yang diiklankan kanal.
• CLI lokal: menggunakan outputFormat yang dikonfigurasi. Target pesan suara dikonversi menjadi Ogg/Opus dan keluaran telefoni dikonversi menjadi PCM mono mentah 16 kHz dengan ffmpeg.
• Google Gemini: mengembalikan PCM mentah 24 kHz. OpenClaw membungkusnya sebagai WAV untuk lampiran audio, mentranskodenya menjadi Opus 48 kHz untuk target pesan suara, dan mengembalikan PCM secara langsung untuk Percakapan/telefoni.
• Gradium: WAV untuk lampiran audio, Opus untuk target pesan suara, dan ulaw_8000 pada 8 kHz untuk telefoni.
• Inworld: MP3 untuk lampiran audio normal, OGG_OPUS native untuk target pesan suara, dan PCM mentah pada 22050 Hz untuk Percakapan/telefoni.
• xAI: MP3 secara bawaan; sintesis berkas audio dapat menggunakan mp3, wav, pcm, mulaw, atau alaw untuk keluaran dengan buffering maupun streaming. Target pesan suara menggunakan MP3 untuk streaming dan fallback dengan buffering karena keluaran pcm, mulaw, dan alaw xAI merupakan audio mentah tanpa header. Sintesis dengan buffering menggunakan endpoint /v1/tts REST batch xAI; textToSpeechStream menggunakan wss://api.x.ai/v1/tts native. Ini bukan kontrak suara waktu nyata. Format pesan suara Opus native tidak didukung.
• Microsoft: menggunakan microsoft.outputFormat (bawaan audio-24khz-48kbitrate-mono-mp3).
  • Transport terpaket menerima outputFormat, tetapi tidak semua format tersedia dari layanan tersebut.
  • Nilai format keluaran mengikuti format keluaran Microsoft Speech (termasuk Ogg/WebM Opus).
  • Telegram sendVoice menerima OGG/MP3/M4A; gunakan OpenAI/ElevenLabs jika Anda memerlukan pesan suara Opus yang terjamin.
  • Jika format keluaran Microsoft yang dikonfigurasi gagal, OpenClaw mencoba kembali dengan MP3.
  • Jika tidak ada penggantian suara eksplisit yang ditetapkan dan suara bahasa Inggris bawaan digunakan, OpenClaw otomatis beralih ke suara neural bahasa Tionghoa (zh-CN-XiaoxiaoNeural, lokal zh-CN) jika teks balasan didominasi CJK.

Format keluaran OpenAI dan ElevenLabs ditetapkan per kanal seperti tercantum di atas.

Perilaku TTS otomatis

Saat messages.tts.auto diaktifkan, OpenClaw:

• Melewati TTS jika balasan sudah berisi media terstruktur.
• Melewati balasan yang sangat singkat (di bawah 10 karakter).
• Meringkas balasan panjang jika ringkasan diaktifkan, menggunakan summaryModel (atau agents.defaults.model.primary).
• Melampirkan audio yang dihasilkan ke balasan.
• Dalam mode: "final", tetap mengirim TTS hanya-audio untuk balasan akhir yang dialirkan setelah aliran teks selesai; media yang dihasilkan melalui normalisasi media kanal yang sama seperti lampiran balasan normal.

Jika balasan melebihi maxLength, OpenClaw tidak pernah melewati audio sepenuhnya:

• Ringkasan aktif (bawaan) dan model ringkasan tersedia: meringkas teks menjadi sekitar maxLength karakter, lalu menyintesis ringkasan tersebut.
• Ringkasan nonaktif, peringkasan gagal, atau tidak tersedia kunci API untuk model ringkasan: memotong teks menjadi maxLength karakter dan menyintesis teks yang telah dipotong.

Balasan -> TTS diaktifkan?  tidak -> kirim teks  ya    -> memiliki media / singkat?           ya    -> kirim teks           tidak -> panjang > batas?                    tidak -> TTS -> lampirkan audio                    ya    -> ringkasan diaktifkan dan tersedia?                             tidak -> potong -> TTS -> lampirkan audio                             ya    -> ringkas -> TTS -> lampirkan audio

Referensi bidang

Alat agen

Alat tts mengonversi teks menjadi ucapan dan mengembalikan lampiran audio untuk pengiriman balasan. Di Feishu, Matrix, Telegram, dan WhatsApp, audio dikirim sebagai pesan suara, bukan sebagai lampiran file. Feishu dan WhatsApp dapat mentranskode keluaran TTS non-Opus pada jalur ini ketika ffmpeg tersedia.

WhatsApp mengirim audio melalui Baileys sebagai pesan suara PTT (audio dengan ptt: true) dan mengirim teks yang terlihat secara terpisah dari audio PTT karena klien tidak secara konsisten menampilkan keterangan pada pesan suara.

Alat ini menerima kolom opsional channel dan timeoutMs; timeoutMs adalah batas waktu permintaan penyedia per panggilan dalam milidetik. Nilai per panggilan menggantikan messages.tts.timeoutMs; batas waktu TTS yang dikonfigurasi menggantikan nilai default penyedia yang ditentukan oleh plugin.

RPC Gateway

Tautan layanan

• Panduan teks ke ucapan OpenAI
• Referensi API Audio OpenAI
• Teks ke ucapan REST Azure Speech
• Penyedia Azure Speech
• Teks ke Ucapan ElevenLabs
• Autentikasi ElevenLabs
• Gradium
• API TTS Inworld
• API MiniMax T2A v2
• API HTTP TTS Volcengine
• Sintesis ucapan Xiaomi MiMo
• node-edge-tts
• Format keluaran Microsoft Speech
• Teks ke ucapan xAI

Terkait

• Ikhtisar media
• Pembuatan musik
• Pembuatan video
• Perintah garis miring
• Plugin panggilan suara