Teks ke ucapan

OpenClaw dapat mengonversi balasan keluar menjadi audio di 14 penyedia ucapan dan mengirim pesan suara native di Feishu, Matrix, Telegram, dan WhatsApp, lampiran audio di tempat lain, serta stream PCM/Ulaw untuk teleponi dan Talk. TTS adalah separuh keluaran-ucapan dari mode stt-tts Talk. Sesi Talk realtime yang native penyedia menyintesis ucapan di dalam penyedia realtime, bukan memanggil jalur TTS ini, sedangkan sesi transcription tidak menyintesis respons suara asisten.

Mulai cepat

Pilih penyedia

OpenAI dan ElevenLabs adalah opsi hosted yang paling andal. Microsoft dan Local CLI berfungsi tanpa kunci API. Lihat matriks penyedia untuk daftar lengkap.

Atur kunci API

Ekspor env var untuk penyedia Anda (misalnya OPENAI_API_KEY, ELEVENLABS_API_KEY). Microsoft dan Local CLI tidak memerlukan kunci.

Aktifkan di config

Atur messages.tts.auto: "always" dan messages.tts.provider:

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

Coba di chat

/tts status menampilkan status saat ini. /tts audio Hello from OpenClaw mengirim balasan audio sekali pakai.

Auto-TTS nonaktif secara default. Jika messages.tts.provider belum diatur, OpenClaw memilih penyedia pertama yang dikonfigurasi dalam urutan auto-select registry. Tool agen tts bawaan hanya untuk niat eksplisit: chat biasa tetap berupa teks kecuali pengguna meminta audio, menggunakan /tts, atau mengaktifkan ucapan Auto-TTS/direktif.

Penyedia yang didukung

Penyedia	Auth	Catatan
Azure Speech	`AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (juga `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`)	Keluaran voice-note Ogg/Opus native dan teleponi.
DeepInfra	`DEEPINFRA_API_KEY`	TTS kompatibel OpenAI. Default ke `hexgrad/Kokoro-82M`.
ElevenLabs	`ELEVENLABS_API_KEY` atau `XI_API_KEY`	Kloning suara, multibahasa, deterministik melalui `seed`; distream untuk pemutaran suara Discord.
Google Gemini	`GEMINI_API_KEY` atau `GOOGLE_API_KEY`	TTS batch Gemini API; sadar persona melalui `promptTemplate: "audio-profile-v1"`.
Gradium	`GRADIUM_API_KEY`	Keluaran voice-note dan teleponi.
Inworld	`INWORLD_API_KEY`	API TTS streaming. Voice-note Opus native dan teleponi PCM.
Local CLI	tidak ada	Menjalankan perintah TTS lokal yang dikonfigurasi.
Microsoft	tidak ada	TTS neural Edge publik melalui `node-edge-tts`. Upaya terbaik, tanpa SLA.
MiniMax	`MINIMAX_API_KEY` (atau Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`)	API T2A v2. Default ke `speech-2.8-hd`.
OpenAI	`OPENAI_API_KEY`	Juga digunakan untuk ringkasan otomatis; mendukung persona `instructions`.
OpenRouter	`OPENROUTER_API_KEY` (dapat menggunakan ulang `models.providers.openrouter.apiKey`)	Model default `hexgrad/kokoro-82m`.
Volcengine	`VOLCENGINE_TTS_API_KEY` atau `BYTEPLUS_SEED_SPEECH_API_KEY` (AppID/token legacy: `VOLCENGINE_TTS_APPID`/`_TOKEN`)	API HTTP BytePlus Seed Speech.
Vydra	`VYDRA_API_KEY`	Penyedia gambar, video, dan ucapan bersama.
xAI	`XAI_API_KEY`	TTS batch xAI. Voice-note Opus native tidak didukung.
Xiaomi MiMo	`XIAOMI_API_KEY`	TTS MiMo melalui penyelesaian chat Xiaomi.

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), sehingga penyedia itu juga harus diautentikasi jika Anda tetap mengaktifkan ringkasan.

Penyedia Microsoft yang dibundel menggunakan layanan TTS neural online Microsoft Edge melalui node-edge-tts. Ini adalah layanan web publik tanpa SLA atau kuota yang dipublikasikan — perlakukan sebagai upaya terbaik. Id penyedia legacy edge dinormalisasi menjadi microsoft dan openclaw doctor --fix menulis ulang config yang dipersistenkan; config baru harus selalu menggunakan microsoft.

Konfigurasi

Config 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",
          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",
          // 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}",
          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 ke prompt desain suara. OpenClaw mengirim prompt tersebut sebagai pesan user TTS 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 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: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

Untuk mengunci persona per agen, atur agents.list[].tts.persona bersama konfigurasi penyedia — ini menggantikan messages.tts.persona global hanya untuk agen tersebut. Urutan presedensi untuk balasan otomatis, /tts audio, /tts status, dan alat agen tts:

messages.tts
agents.list[].tts aktif
penggantian saluran, ketika saluran mendukung channels.<channel>.tts
penggantian akun, ketika saluran meneruskan channels.<channel>.accounts.<id>.tts
preferensi lokal /tts untuk host ini
direktif inline [[tts:...]] ketika penggantian model diaktifkan

Penggantian saluran 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 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 yang stabil dan dapat diterapkan secara deterministik di berbagai penyedia. Persona dapat memilih satu penyedia, mendefinisikan intent prompt yang netral penyedia, dan membawa binding khusus penyedia untuk suara, model, template prompt, seed, dan pengaturan suara.

Persona minimal

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "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",
              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:

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

Pemilihan penyedia berjalan dengan yang eksplisit terlebih dahulu:

Penggantian langsung (CLI, Gateway, Talk, direktif TTS yang diizinkan).
Preferensi lokal /tts provider <id>.
provider dari persona aktif.
messages.tts.provider.
Pemilihan otomatis registry.

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

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

Cara penyedia menggunakan prompt persona

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

Google Gemini

Membungkus bidang prompt persona dalam struktur prompt TTS Gemini hanya ketika konfigurasi penyedia Google efektif mengatur promptTemplate: "audio-profile-v1" atau personaPrompt. Bidang lama audioProfile dan speakerName masih ditambahkan di awal sebagai teks prompt khusus Google. Tag audio inline seperti [whispers] atau [laughs] di dalam blok [[tts:text]] dipertahankan di dalam transkrip Gemini; OpenClaw tidak membuat tag ini.

OpenAI

Memetakan bidang prompt persona ke bidang permintaan instructions hanya ketika tidak ada instructions OpenAI eksplisit yang dikonfigurasi. instructions eksplisit selalu menang.

Penyedia lain

Hanya menggunakan binding persona khusus penyedia di bawah personas.<id>.providers.<provider>. Bidang prompt persona diabaikan kecuali penyedia mengimplementasikan pemetaan prompt persona sendiri.

Kebijakan fallback

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

Kebijakan	Perilaku
`preserve-persona`	Default. Bidang prompt netral penyedia tetap tersedia; penyedia dapat menggunakannya atau mengabaikannya.
`provider-defaults`	Persona dihilangkan dari persiapan prompt untuk percobaan tersebut; penyedia menggunakan default netralnya sementara fallback ke penyedia lain berlanjut.
`fail`	Lewati percobaan penyedia tersebut dengan `reasonCode: "not_configured"` dan `personaBinding: "missing"`. Penyedia fallback tetap dicoba.

Seluruh permintaan TTS hanya gagal ketika setiap penyedia yang dicoba dilewati atau gagal. Pemilihan penyedia sesi Talk bersifat tercakup sesi. Klien Talk harus memilih id penyedia, id model, id suara, dan lokal dari talk.catalog dan 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 hanya boleh muncul di audio:

Here you go.

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

Ketika messages.tts.auto bernilai "tagged", direktif diperlukan untuk memicu audio. Pengiriman blok streaming menghapus direktif dari teks yang terlihat sebelum saluran melihatnya, bahkan ketika terpisah di beberapa blok yang bersebelahan. 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 (pitch integer 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 perpindahan penyedia sambil tetap membuat knob 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>

Perintah memerlukan pengirim yang berwenang (aturan allowlist/pemilik berlaku) dan commands.text atau pendaftaran perintah native harus diaktifkan.

Catatan perilaku:

/tts on menulis preferensi TTS lokal ke always; /tts off menulisnya ke off.
/tts chat on|off|default menulis penggantian TTS otomatis tercakup 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 sekali. Ini hanya menyimpan hash dari balasan tersebut pada entri sesi untuk menekan pengiriman suara duplikat.
/tts audio membuat 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 sudah disanitasi ketika 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.

Bidang tersimpan	Efek
`auto`	Penggantian TTS otomatis lokal (`always`, `off`, …)
`provider`	Penggantian penyedia utama lokal
`persona`	Penggantian persona lokal
`maxLength`	Ambang ringkasan (default `1500` karakter)
`summarize`	Toggle ringkasan (default `true`)

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

Format output (tetap)

Pengiriman suara TTS digerakkan oleh kapabilitas saluran. Plugin saluran mengiklankan apakah TTS bergaya suara harus meminta target voice-note native 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 pesan suara yang baik.
Feishu / WhatsApp: ketika balasan catatan suara dibuat sebagai MP3/WebM/WAV/M4A atau berkas audio lain yang mungkin, plugin kanal mentranskodenya ke 48kHz Ogg/Opus dengan ffmpeg sebelum mengirim pesan suara native. WhatsApp mengirim hasilnya melalui payload Baileys audio dengan ptt: true dan audio/ogg; codecs=opus. Jika konversi gagal, Feishu menerima berkas asli sebagai lampiran; pengiriman WhatsApp gagal alih-alih memposting payload PTT yang tidak kompatibel.
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 transkoding.
Xiaomi MiMo: MP3 secara default, atau WAV saat dikonfigurasi. Untuk target catatan suara yang diiklankan kanal, OpenClaw mentranskode keluaran Xiaomi ke Opus 48kHz dengan ffmpeg sebelum pengiriman ketika kanal mengiklankan transkoding.
CLI lokal: menggunakan outputFormat yang dikonfigurasi. Target catatan suara dikonversi ke Ogg/Opus dan keluaran telefoni dikonversi ke PCM mono mentah 16 kHz dengan ffmpeg.
Google Gemini: TTS Gemini API mengembalikan PCM mentah 24kHz. OpenClaw membungkusnya sebagai WAV untuk lampiran audio, mentranskodenya ke Opus 48kHz untuk target catatan suara, dan mengembalikan PCM 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 mentah pada 22050 Hz untuk Talk/telefoni.
xAI: MP3 secara default; responseFormat dapat berupa mp3, wav, pcm, mulaw, atau alaw. OpenClaw menggunakan endpoint TTS batch REST xAI dan mengembalikan lampiran audio lengkap; WebSocket TTS streaming xAI tidak digunakan oleh jalur penyedia ini. Format catatan suara Opus native tidak didukung oleh jalur ini.
Microsoft: menggunakan microsoft.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
- Transport yang dibundel 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 terstruktur.
Melewati balasan yang sangat pendek (di bawah 10 karakter).
Meringkas balasan panjang ketika 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 final yang di-stream setelah stream teks selesai; media yang dihasilkan melewati 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 / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

Format keluaran menurut kanal

Target	Format
Feishu / Matrix / Telegram / WhatsApp	Balasan catatan suara lebih memilih Opus (`opus_48000_64` dari ElevenLabs, `opus` dari OpenAI). 48 kHz / 64 kbps menyeimbangkan kejernihan dan ukuran.
Kanal lain	MP3 (`mp3_44100_128` dari ElevenLabs, `mp3` dari OpenAI). Default 44,1 kHz / 128 kbps untuk ucapan.
Talk / telefoni	PCM native penyedia (Inworld 22050 Hz, Google 24 kHz), atau `ulaw_8000` dari Gradium untuk telefoni.

Catatan per penyedia:

Transkoding Feishu / WhatsApp: Ketika balasan catatan suara masuk sebagai MP3/WebM/WAV/M4A, plugin kanal mentranskode ke Ogg/Opus 48 kHz dengan ffmpeg. WhatsApp mengirim melalui Baileys dengan ptt: true dan audio/ogg; codecs=opus. Jika konversi gagal: Feishu fallback ke melampirkan berkas 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 keluaran telefoni ke PCM mono mentah 16 kHz.
Google Gemini: Mengembalikan PCM mentah 24 kHz. OpenClaw membungkus sebagai WAV untuk lampiran, mentranskode ke Opus 48 kHz untuk target catatan suara, mengembalikan PCM langsung untuk Talk/telefoni.
Inworld: Lampiran MP3, catatan suara OGG_OPUS native, PCM mentah 22050 Hz untuk Talk/telefoni.
xAI: MP3 secara default; responseFormat dapat berupa mp3|wav|pcm|mulaw|alaw. Menggunakan endpoint batch REST 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 memerlukan pesan suara Opus yang terjamin. Jika format Microsoft yang dikonfigurasi gagal, OpenClaw mencoba lagi dengan MP3.

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

Referensi bidang

Top-level messages.tts.*

auto

"off" | "always" | "inbound" | "tagged"

Mode Auto-TTS. inbound hanya mengirim audio setelah pesan suara masuk; tagged hanya mengirim audio ketika balasan menyertakan direktif [[tts:...]] atau blok [[tts:text]].

enabled

boolean

usang

Toggle lama. openclaw doctor --fix memigrasikan ini ke auto.

mode

"final" | "all"

default:"final"

"all" menyertakan balasan alat/blok selain balasan final.

provider

string

Id penyedia ucapan. Ketika tidak disetel, OpenClaw menggunakan penyedia pertama yang dikonfigurasi dalam urutan pemilihan otomatis registry. provider: "edge" lama ditulis ulang menjadi "microsoft" oleh openclaw doctor --fix.

persona

string

Id persona aktif dari personas. Dinormalisasi ke huruf kecil.

personas.<id>

object

Identitas lisan yang stabil. Bidang: label, description, provider, fallbackPolicy, prompt, providers.<provider>. Lihat Persona.

summaryModel

string

Model murah untuk ringkasan otomatis; default ke agents.defaults.model.primary. Menerima provider/model atau alias model yang dikonfigurasi.

modelOverrides

object

Izinkan model mengeluarkan direktif TTS. enabled default ke true; allowProvider default ke false.

providers.<id>

object

Pengaturan milik penyedia yang diberi kunci berdasarkan id penyedia ucapan. Blok langsung lama (messages.tts.openai, .elevenlabs, .microsoft, .edge) ditulis ulang oleh openclaw doctor --fix; commit hanya messages.tts.providers.<id>.

maxTextLength

number

Batas keras untuk karakter masukan TTS. /tts audio gagal jika terlampaui.

timeoutMs

number

Timeout permintaan dalam milidetik.

prefsPath

string

Timpa jalur JSON prefs lokal (penyedia/batas/ringkasan). Default ~/.openclaw/settings/tts.json.

Azure Speech

apiKey

string

Env: AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY, atau SPEECH_KEY.

region

string

Region Azure Speech (misalnya eastus). Env: AZURE_SPEECH_REGION atau SPEECH_REGION.

endpoint

string

Override endpoint Azure Speech opsional (alias baseUrl).

speakerVoice

string

ShortName suara Azure. Default en-US-JennyNeural. Alias lama: voice.

lang

string

Kode bahasa SSML. Default en-US.

outputFormat

string

X-Microsoft-OutputFormat Azure untuk audio standar. Default audio-24khz-48kbitrate-mono-mp3.

voiceNoteOutputFormat

string

X-Microsoft-OutputFormat Azure untuk keluaran catatan suara. Default ogg-24khz-16bit-mono-opus.

ElevenLabs

apiKey

string

Fallback ke ELEVENLABS_API_KEY atau XI_API_KEY.

model

string

Id model (misalnya eleven_multilingual_v2, eleven_v3).

speakerVoiceId

string

Id suara ElevenLabs. Alias lama: voiceId.

voiceSettings

object

stability, similarityBoost, style (masing-masing 0..1), useSpeakerBoost (true|false), speed (0.5..2.0, 1.0 = normal).

applyTextNormalization

"auto" | "on" | "off"

Mode normalisasi teks.

languageCode

string

ISO 639-1 2 huruf (misalnya en, de).

seed

number

Bilangan bulat 0..4294967295 untuk determinisme upaya terbaik.

baseUrl

string

Timpa URL dasar API ElevenLabs.

Google Gemini

apiKey

string

Fallback ke GEMINI_API_KEY / GOOGLE_API_KEY. Jika dihilangkan, TTS dapat menggunakan kembali models.providers.google.apiKey sebelum fallback env.

model

string

Model TTS Gemini. Default gemini-3.1-flash-tts-preview.

speakerVoice

string

Nama suara siap pakai Gemini. Default Kore. Alias lama: voiceName, voice.

audioProfile

string

Prompt gaya bahasa alami yang ditambahkan sebelum teks lisan.

speakerName

string

Label pembicara opsional yang ditambahkan sebelum teks lisan ketika prompt Anda menggunakan pembicara bernama.

promptTemplate

"audio-profile-v1"

Setel ke audio-profile-v1 untuk membungkus bidang prompt persona aktif dalam struktur prompt TTS Gemini yang deterministik.

personaPrompt

string

Teks prompt persona ekstra khusus Google yang ditambahkan ke Catatan Sutradara template.

baseUrl

string

Hanya https://generativelanguage.googleapis.com yang diterima.

Gradium

apiKey

string

Lingkungan: GRADIUM_API_KEY.

baseUrl

string

Bawaan https://api.gradium.ai.

speakerVoiceId

string

Bawaan Emma (YTpq7expH9539ERJ). Alias lama: voiceId.

Inworld

Primer Inworld

apiKey

string

Lingkungan: INWORLD_API_KEY.

baseUrl

string

Bawaan https://api.inworld.ai.

modelId

string

Bawaan inworld-tts-1.5-max. Juga: inworld-tts-1.5-mini, inworld-tts-1-max, inworld-tts-1.

speakerVoiceId

string

Bawaan Sarah. Alias lama: voiceId.

temperature

number

Suhu sampling 0..2.

Local CLI (tts-local-cli)

command

string

Executable lokal atau string perintah untuk CLI TTS.

args

string[]

Argumen perintah. Mendukung placeholder {{Text}}, {{OutputPath}}, {{OutputDir}}, {{OutputBase}}.

outputFormat

"mp3" | "opus" | "wav"

Format keluaran CLI yang diharapkan. Bawaan mp3 untuk lampiran audio.

timeoutMs

number

Timeout perintah dalam milidetik. Bawaan 120000.

cwd

string

Direktori kerja perintah opsional.

env

Record<string, string>

Override lingkungan opsional untuk perintah.

Microsoft (no API key)

enabled

boolean

default:"true"

Izinkan penggunaan speech Microsoft.

speakerVoice

string

Nama suara neural Microsoft (mis. en-US-MichelleNeural). Alias lama: voice.

lang

string

Kode bahasa (mis. en-US).

outputFormat

string

Format keluaran Microsoft. Bawaan audio-24khz-48kbitrate-mono-mp3. Tidak semua format didukung oleh transport berbasis Edge yang dibundel.

rate / pitch / volume

string

String persentase (mis. +10%, -5%).

saveSubtitles

boolean

Tulis subtitel JSON bersama file audio.

proxy

string

URL proxy untuk permintaan speech Microsoft.

timeoutMs

number

Override timeout permintaan (md).

edge.*

object

usang

Alias lama. Jalankan openclaw doctor --fix untuk menulis ulang config tersimpan ke providers.microsoft.

MiniMax

apiKey

string

Menggunakan fallback ke MINIMAX_API_KEY. Autentikasi Token Plan melalui MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY, atau MINIMAX_CODING_API_KEY.

baseUrl

string

Bawaan https://api.minimax.io. Lingkungan: MINIMAX_API_HOST.

model

string

Bawaan speech-2.8-hd. Lingkungan: MINIMAX_TTS_MODEL.

speakerVoiceId

string

Bawaan English_expressive_narrator. Lingkungan: MINIMAX_TTS_VOICE_ID. Alias lama: voiceId.

speed

number

0.5..2.0. Bawaan 1.0.

vol

number

(0, 10]. Bawaan 1.0.

pitch

number

Integer -12..12. Bawaan 0. Nilai pecahan dipotong sebelum permintaan.

OpenAI

apiKey

string

Menggunakan fallback ke OPENAI_API_KEY.

model

string

ID model TTS OpenAI (mis. gpt-4o-mini-tts).

speakerVoice

string

Nama suara (mis. alloy, cedar). Alias lama: voice.

instructions

string

Kolom instructions OpenAI eksplisit. Saat diatur, kolom prompt persona tidak dipetakan otomatis.

extraBody / extra_body

Record<string, unknown>

Kolom JSON ekstra yang digabungkan ke body permintaan /audio/speech setelah kolom TTS OpenAI yang dihasilkan. Gunakan ini untuk endpoint yang kompatibel dengan OpenAI seperti Kokoro yang memerlukan kunci khusus penyedia seperti lang; kunci prototype yang tidak aman diabaikan.

baseUrl

string

Override endpoint TTS OpenAI. Urutan resolusi: config → OPENAI_TTS_BASE_URL → https://api.openai.com/v1. Nilai non-bawaan diperlakukan sebagai endpoint TTS yang kompatibel dengan OpenAI, sehingga nama model dan suara kustom diterima.

OpenRouter

apiKey

string

Lingkungan: OPENROUTER_API_KEY. Dapat menggunakan ulang models.providers.openrouter.apiKey.

baseUrl

string

Bawaan https://openrouter.ai/api/v1. https://openrouter.ai/v1 lama dinormalisasi.

model

string

Bawaan hexgrad/kokoro-82m. Alias: modelId.

speakerVoice

string

Bawaan af_alloy. Alias lama: voice, voiceId.

responseFormat

"mp3" | "pcm"

Bawaan mp3.

speed

number

Override kecepatan bawaan penyedia.

Volcengine (BytePlus Seed Speech)

apiKey

string

Lingkungan: VOLCENGINE_TTS_API_KEY atau BYTEPLUS_SEED_SPEECH_API_KEY.

resourceId

string

Bawaan seed-tts-1.0. Lingkungan: VOLCENGINE_TTS_RESOURCE_ID. Gunakan seed-tts-2.0 saat proyek Anda memiliki hak TTS 2.0.

appKey

string

Header kunci aplikasi. Bawaan aGjiRDfUWi. Lingkungan: VOLCENGINE_TTS_APP_KEY.

baseUrl

string

Override endpoint HTTP Seed Speech TTS. Lingkungan: VOLCENGINE_TTS_BASE_URL.

speakerVoice

string

Jenis suara. Bawaan en_female_anna_mars_bigtts. Lingkungan: VOLCENGINE_TTS_VOICE. Alias lama: voice.

speedRatio

number

Rasio kecepatan bawaan penyedia.

emotion

string

Tag emosi bawaan penyedia.

appId / token / cluster

string

usang

Kolom Volcengine Speech Console lama. Lingkungan: VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOLCENGINE_TTS_CLUSTER (bawaan volcano_tts).

xAI

apiKey

string

Lingkungan: XAI_API_KEY.

baseUrl

string

Bawaan https://api.x.ai/v1. Lingkungan: XAI_BASE_URL.

speakerVoiceId

string

Bawaan eve. Suara live: ara, eve, leo, rex, sal, una. Alias lama: voiceId.

language

string

Kode bahasa BCP-47 atau auto. Bawaan en.

responseFormat

"mp3" | "wav" | "pcm" | "mulaw" | "alaw"

Bawaan mp3.

speed

number

Override kecepatan bawaan penyedia.

Xiaomi MiMo

apiKey

string

Lingkungan: XIAOMI_API_KEY.

baseUrl

string

Bawaan https://api.xiaomimimo.com/v1. Lingkungan: XIAOMI_BASE_URL.

model

string

Bawaan mimo-v2.5-tts. Lingkungan: XIAOMI_TTS_MODEL. Juga mendukung mimo-v2-tts dan mimo-v2.5-tts-voicedesign.

speakerVoice

string

Bawaan mimo_default untuk model suara preset. Lingkungan: XIAOMI_TTS_VOICE. Alias lama: voice. Tidak dikirim untuk mimo-v2.5-tts-voicedesign.

format

"mp3" | "wav"

Bawaan mp3. Lingkungan: XIAOMI_TTS_FORMAT.

style

string

Instruksi gaya bahasa alami opsional yang dikirim sebagai pesan pengguna; tidak diucapkan. Untuk mimo-v2.5-tts-voicedesign, ini adalah prompt desain suara; OpenClaw menyediakan bawaan saat dihilangkan.

Alat agen

Alat tts mengonversi teks menjadi speech dan mengembalikan lampiran audio untuk pengiriman balasan. Di Feishu, Matrix, Telegram, dan WhatsApp, audio dikirim sebagai pesan suara, bukan lampiran file. 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 secara konsisten merender caption pada catatan suara. Alat ini menerima kolom channel dan timeoutMs opsional; timeoutMs adalah timeout permintaan penyedia per panggilan dalam milidetik. Nilai per panggilan mengesampingkan messages.tts.timeoutMs; timeout TTS yang dikonfigurasi mengesampingkan bawaan penyedia apa pun yang ditulis Plugin.

RPC Gateway

Metode	Tujuan
`tts.status`	Baca status TTS saat ini dan upaya terakhir.
`tts.enable`	Atur preferensi otomatis lokal ke `always`.
`tts.disable`	Atur preferensi otomatis lokal ke `off`.
`tts.convert`	Teks satu kali → audio.
`tts.setProvider`	Atur preferensi penyedia lokal.
`tts.setPersona`	Atur preferensi persona lokal.
`tts.providers`	Cantumkan penyedia yang dikonfigurasi dan statusnya.

Mulai cepat

Penyedia yang didukung

Konfigurasi

Penggantian suara per agen

Persona

Persona minimal

Persona lengkap (prompt netral penyedia)

Resolusi persona

Cara penyedia menggunakan prompt persona

Kebijakan fallback

Direktif berbasis model

Perintah slash

Preferensi per pengguna

Format output (tetap)

Perilaku Auto-TTS

Format keluaran menurut kanal

Referensi bidang

Primer Inworld

Alat agen

RPC Gateway

Tautan layanan

Terkait

​Mulai cepat

​Penyedia yang didukung

​Konfigurasi

​Penggantian suara per agen

​Persona

​Persona minimal

​Persona lengkap (prompt netral penyedia)

​Resolusi persona

​Cara penyedia menggunakan prompt persona

​Kebijakan fallback

​Direktif berbasis model

​Perintah slash

​Preferensi per pengguna

​Format output (tetap)

​Perilaku Auto-TTS

​Format keluaran menurut kanal

​Referensi bidang

​Primer Inworld

​Alat agen

​RPC Gateway

​Tautan layanan

​Terkait

Mulai cepat

Penyedia yang didukung

Konfigurasi

Penggantian suara per agen

Persona

Persona minimal

Persona lengkap (prompt netral penyedia)

Resolusi persona

Cara penyedia menggunakan prompt persona

Kebijakan fallback

Direktif berbasis model

Perintah slash

Preferensi per pengguna

Format output (tetap)

Perilaku Auto-TTS

Format keluaran menurut kanal

Referensi bidang

Primer Inworld

Alat agen

RPC Gateway

Tautan layanan

Terkait