Teks ke ucapan

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

TTS adalah separuh keluaran ucapan dari mode stt-tts Talk. Sesi Talk realtime native penyedia menyintesis ucapan di dalam penyedia realtime, bukan memanggil jalur TTS ini, sedangkan sesi transcription tidak menyintesis respons suara asisten.

# Mulai cepat

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

# Penyedia yang didukung

Jika beberapa penyedia dikonfigurasi, penyedia yang dipilih digunakan terlebih dahulu dan yang lain menjadi opsi fallback. Ringkasan otomatis menggunakan summaryModel (atau agents.defaults.model.primary), jadi penyedia itu juga harus diautentikasi jika Anda tetap mengaktifkan ringkasan.

# Konfigurasi

Konfigurasi TTS berada di bawah messages.tts dalam ~/.openclaw/openclaw.json. Pilih preset dan sesuaikan blok penyedia:

{
messages: {
tts: {
  auto: "always",
  provider: "azure-speech",
  providers: {
    "azure-speech": {
      apiKey: "${AZURE_SPEECH_KEY}",
      region: "eastus",
      voice: "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",
      voiceId: "EXAVITQu4vr4xnSDxMaL",
    },
  },
},
},
}

{
messages: {
tts: {
  auto: "always",
  provider: "google",
  providers: {
    google: {
      apiKey: "${GEMINI_API_KEY}",
      model: "gemini-3.1-flash-tts-preview",
      voiceName: "Kore",
      // Optional natural-language style prompts:
      // audioProfile: "Speak in a calm, podcast-host tone.",
      // speakerName: "Alex",
    },
  },
},
},
}

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

{
messages: {
tts: {
  auto: "always",
  provider: "inworld",
  providers: {
    inworld: {
      apiKey: "${INWORLD_API_KEY}",
      modelId: "inworld-tts-1.5-max",
      voiceId: "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,
      voice: "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",
      voiceId: "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",
      voice: "alloy",
    },
    elevenlabs: {
      apiKey: "${ELEVENLABS_API_KEY}",
      model: "eleven_multilingual_v2",
      voiceId: "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",
      voice: "af_alloy",
      responseFormat: "mp3",
    },
  },
},
},
}

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

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

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

# Penggantian suara per agen

Gunakan agents.list[].tts ketika satu agen harus berbicara dengan penyedia, suara, model, persona, atau mode Auto-TTS yang berbeda. Blok agen melakukan deep-merge di atas messages.tts, sehingga kredensial penyedia dapat tetap berada di 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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

Untuk menetapkan persona per agen, atur agents.list[].tts.persona bersama konfigurasi penyedia — 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 kanal, saat kanal mendukung channels.<channel>.tts
4. penggantian akun, saat kanal meneruskan channels.<channel>.accounts.<id>.tts
5. preferensi /tts lokal untuk host ini
6. direktif inline [[tts:...]] saat penggantian model diaktifkan

Penggantian kanal dan akun menggunakan bentuk yang sama seperti messages.tts dan melakukan deep-merge di atas lapisan sebelumnya, sehingga kredensial penyedia bersama dapat tetap berada di messages.tts sementara kanal atau akun bot hanya mengubah suara, 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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

# Persona

Persona adalah identitas tutur yang stabil dan dapat diterapkan secara deterministik di seluruh penyedia. Persona dapat memprioritaskan satu penyedia, mendefinisikan intensi prompt yang netral penyedia, dan membawa binding khusus penyedia untuk suara, model, templat prompt, seed, dan pengaturan suara.

# Persona minimal

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

# Persona lengkap (prompt netral penyedia)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              voiceName: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
            elevenlabs: {
              voiceId: "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 berjalan dengan eksplisit lebih dahulu:

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 registri.

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

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

# Cara penyedia menggunakan prompt persona

Field prompt persona (profile, scene, sampleContext, style, accent, pacing, constraints) bersifat netral penyedia. Setiap penyedia memutuskan sendiri cara menggunakannya:

# Kebijakan fallback

fallbackPolicy mengontrol perilaku saat persona tidak memiliki binding untuk penyedia yang dicoba:

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

Pemilihan penyedia sesi Talk berlaku dalam cakupan sesi. Klien Talk sebaiknya memilih id penyedia, id model, id suara, dan locale dari talk.catalog lalu meneruskannya melalui sesi Talk atau permintaan handoff. Membuka sesi suara tidak boleh mengubah messages.tts atau default penyedia Talk global.

# Direktif berbasis model

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

Here you go.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

Saat messages.tts.auto bernilai "tagged", direktif wajib ada untuk memicu audio. Pengiriman blok streaming menghapus direktif dari teks yang terlihat sebelum kanal melihatnya, bahkan saat terbagi di beberapa blok bersebelahan.

provider=... diabaikan kecuali modelOverrides.allowProvider: true. Saat balasan mendeklarasikan provider=..., kunci lain dalam direktif tersebut hanya diurai 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)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (pitch 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 pergantian penyedia sambil tetap membuat kenop lain dapat dikonfigurasi:

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

# Perintah slash

Satu perintah /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 bercakupan sesi untuk chat 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 sebagai audio satu kali. Perintah ini hanya menyimpan hash balasan tersebut pada entri sesi untuk menekan pengiriman suara duplikat.
• /tts audio menghasilkan balasan audio sekali pakai (tidak mengaktifkan TTS).
• limit dan summary disimpan di 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 endpoint kustom yang telah disanitasi saat TTS diaktifkan.

# Preferensi per pengguna

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

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

# Format output (tetap)

Pengiriman suara TTS digerakkan oleh kemampuan kanal. Plugin kanal mengiklankan apakah TTS bergaya suara harus meminta target native voice-note kepada penyedia atau mempertahankan sintesis audio-file normal dan hanya menandai output yang kompatibel untuk pengiriman suara.

• Kanal yang mendukung catatan suara: balasan catatan suara lebih memilih Opus (opus_48000_64 dari ElevenLabs, opus dari OpenAI).
  • 48kHz / 64kbps adalah kompromi yang baik untuk pesan suara.
• Feishu / WhatsApp: ketika balasan catatan suara dihasilkan sebagai MP3/WebM/WAV/M4A atau file audio lain yang kemungkinan sesuai, Plugin kanal mentranskodenya ke Ogg/Opus 48kHz dengan ffmpeg sebelum mengirim pesan suara native. WhatsApp mengirim hasilnya melalui payload audio Baileys dengan ptt: true dan audio/ogg; codecs=opus. Jika konversi gagal, Feishu menerima file asli sebagai lampiran; pengiriman WhatsApp gagal alih-alih memposting payload PTT yang tidak kompatibel.
• BlueBubbles: mempertahankan sintesis provider pada jalur file audio normal; keluaran MP3 dan CAF ditandai untuk pengiriman memo suara iMessage.
• Kanal lain: MP3 (mp3_44100_128 dari ElevenLabs, mp3 dari OpenAI).
  • 44.1kHz / 128kbps adalah keseimbangan default untuk kejernihan ucapan.
• MiniMax: MP3 (model speech-2.8-hd, laju sampel 32kHz) untuk lampiran audio normal. Untuk target catatan suara yang diiklankan kanal, OpenClaw mentranskode MP3 MiniMax ke Opus 48kHz dengan ffmpeg sebelum pengiriman ketika kanal mengiklankan transcoding.
• Xiaomi MiMo: MP3 secara default, atau WAV ketika dikonfigurasi. Untuk target catatan suara yang diiklankan kanal, OpenClaw mentranskode keluaran Xiaomi ke Opus 48kHz dengan ffmpeg sebelum pengiriman ketika kanal mengiklankan transcoding.
• CLI Lokal: menggunakan outputFormat yang dikonfigurasi. Target catatan suara dikonversi ke Ogg/Opus dan keluaran telefoni dikonversi ke PCM mono 16 kHz raw dengan ffmpeg.
• Google Gemini: TTS Gemini API mengembalikan PCM raw 24kHz. OpenClaw membungkusnya sebagai WAV untuk lampiran audio, mentranskodenya ke Opus 48kHz untuk target catatan suara, dan mengembalikan PCM secara langsung untuk Talk/telefoni.
• Gradium: WAV untuk lampiran audio, Opus untuk target catatan suara, dan ulaw_8000 pada 8 kHz untuk telefoni.
• Inworld: MP3 untuk lampiran audio normal, OGG_OPUS native untuk target catatan suara, dan PCM raw pada 22050 Hz untuk Talk/telefoni.
• xAI: MP3 secara default; responseFormat dapat berupa mp3, wav, pcm, mulaw, atau alaw. OpenClaw menggunakan endpoint TTS REST batch xAI dan mengembalikan lampiran audio lengkap; WebSocket TTS streaming xAI tidak digunakan oleh jalur provider ini. Format catatan suara Opus native tidak didukung oleh jalur ini.
• Microsoft: menggunakan microsoft.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
  • Transport bawaan menerima outputFormat, tetapi tidak semua format tersedia dari layanan.
  • 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 lagi dengan MP3.

Format keluaran OpenAI/ElevenLabs ditetapkan per kanal (lihat di atas).

# Perilaku Auto-TTS

Ketika messages.tts.auto diaktifkan, OpenClaw:

• Melewati TTS jika balasan sudah berisi media atau directive MEDIA:.
• Melewati balasan yang sangat pendek (di bawah 10 karakter).
• Merangkum balasan panjang ketika ringkasan diaktifkan, menggunakan summaryModel (atau agents.defaults.model.primary).
• Melampirkan audio yang dihasilkan ke balasan.
• Dalam mode: "final", tetap mengirim TTS audio-saja untuk balasan final yang di-stream setelah stream teks selesai; media yang dihasilkan melalui normalisasi media kanal yang sama seperti lampiran balasan normal.

Jika balasan melebihi maxLength dan ringkasan nonaktif (atau tidak ada kunci API untuk model ringkasan), audio dilewati dan balasan teks normal dikirim.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / MEDIA: / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

# Format keluaran berdasarkan kanal

Catatan per penyedia:

• Transkode Feishu / WhatsApp: Saat balasan catatan suara masuk sebagai MP3/WebM/WAV/M4A, plugin saluran mentranskode ke Ogg/Opus 48 kHz dengan ffmpeg. WhatsApp mengirim melalui Baileys dengan ptt: true dan audio/ogg; codecs=opus. Jika konversi gagal: Feishu kembali melampirkan file asli; pengiriman WhatsApp gagal alih-alih memposting payload PTT yang tidak kompatibel.
• MiniMax / Xiaomi MiMo: MP3 default (32 kHz untuk MiniMax speech-2.8-hd); ditranskode ke Opus 48 kHz untuk target catatan suara melalui ffmpeg.
• CLI lokal: Menggunakan outputFormat yang dikonfigurasi. Target catatan suara dikonversi ke Ogg/Opus dan output telefoni ke PCM mono mentah 16 kHz.
• Google Gemini: Mengembalikan PCM mentah 24 kHz. OpenClaw membungkusnya sebagai WAV untuk lampiran, mentranskode ke Opus 48 kHz untuk target catatan suara, mengembalikan PCM secara langsung untuk Talk/telefoni.
• Inworld: Lampiran MP3, catatan suara native OGG_OPUS, PCM mentah 22050 Hz untuk Talk/telefoni.
• xAI: MP3 secara default; responseFormat dapat berupa mp3|wav|pcm|mulaw|alaw. Menggunakan endpoint REST batch xAI — TTS WebSocket streaming tidak digunakan. Format catatan suara Opus native tidak didukung.
• Microsoft: Menggunakan microsoft.outputFormat (default audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice menerima OGG/MP3/M4A; gunakan OpenAI/ElevenLabs jika Anda membutuhkan pesan suara Opus yang dijamin. Jika format Microsoft yang dikonfigurasi gagal, OpenClaw mencoba lagi dengan MP3.

Format output OpenAI dan ElevenLabs ditetapkan per saluran seperti tercantum di atas.

# 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 lampiran berkas. Feishu dan WhatsApp dapat mentranskode keluaran TTS non-Opus di jalur ini saat ffmpeg tersedia.

WhatsApp mengirim audio melalui Baileys sebagai catatan suara PTT (audio dengan ptt: true) dan mengirim teks terlihat secara terpisah dari audio PTT karena klien tidak selalu merender teks keterangan pada catatan suara.

Alat ini menerima kolom opsional channel dan timeoutMs; timeoutMs adalah tenggat waktu permintaan penyedia per panggilan dalam milidetik.

# 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 slash
• Plugin panggilan suara