Metinden konuşmaya

OpenClaw, giden yanıtları 14 konuşma sağlayıcısı genelinde sese dönüştürebilir ve Feishu, Matrix, Telegram ve WhatsApp üzerinde yerel sesli mesajlar, diğer her yerde ses ekleri ve telefon ile Talk için PCM/Ulaw akışları iletebilir.

TTS, Talk'ın stt-tts modunun konuşma çıktısı yarısıdır. Sağlayıcıya yerel realtime Talk oturumları, bu TTS yolunu çağırmak yerine konuşmayı gerçek zamanlı sağlayıcının içinde sentezler; transcription oturumları ise asistan için sesli yanıt sentezlemez.

Hızlı başlangıç

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

Desteklenen sağlayıcılar

Birden fazla sağlayıcı yapılandırılmışsa, önce seçilen sağlayıcı kullanılır ve diğerleri yedek seçeneklerdir. Otomatik özet summaryModel (veya agents.defaults.model.primary) kullanır; bu nedenle özetleri etkin tutarsanız o sağlayıcının da kimliğinin doğrulanmış olması gerekir.

Yapılandırma

TTS yapılandırması ~/.openclaw/openclaw.json içinde messages.tts altında bulunur. Bir ön ayar seçin ve sağlayıcı bloğunu uyarlayın:

{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",    },  },},},}

Ajan başına ses geçersiz kılmaları

Bir ajanın farklı bir sağlayıcı, ses, model, persona veya Auto-TTS modu ile konuşması gerektiğinde agents.list[].tts kullanın. Ajan bloğu messages.tts üzerine derin birleştirme yapar; bu nedenle sağlayıcı kimlik bilgileri genel sağlayıcı yapılandırmasında kalabilir:

{  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" },          },        },      },    ],  },}

Aracı başına bir persona sabitlemek için sağlayıcı yapılandırmasının yanında agents.list[].tts.persona ayarlayın; bu, yalnızca ilgili aracı için genel messages.tts.persona değerini geçersiz kılar.

Otomatik yanıtlar, /tts audio, /tts status ve tts aracı aracı için öncelik sırası:

1. messages.tts
2. etkin agents.list[].tts
3. kanal channels.<channel>.tts destekliyorsa kanal geçersiz kılması
4. kanal channels.<channel>.accounts.<id>.tts geçiriyorsa hesap geçersiz kılması
5. bu ana makine için yerel /tts tercihleri
6. model geçersiz kılmaları etkinleştirildiğinde satır içi [[tts:...]] yönergeleri

Kanal ve hesap geçersiz kılmaları messages.tts ile aynı şekli kullanır ve önceki katmanların üzerine derin birleştirme yapar; böylece paylaşılan sağlayıcı kimlik bilgileri messages.tts içinde kalırken bir kanal veya bot hesabı yalnızca sesi, modeli, personayı veya otomatik modu değiştirebilir:

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

Personalar

Persona, sağlayıcılar arasında deterministik olarak uygulanabilen kararlı bir konuşma kimliğidir. Tek bir sağlayıcıyı tercih edebilir, sağlayıcıdan bağımsız istem amacını tanımlayabilir ve sesler, modeller, istem şablonları, seed değerleri ve ses ayarları için sağlayıcıya özel bağlamaları taşıyabilir.

Minimal persona

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

Tam persona (sağlayıcıdan bağımsız istem)

{  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,              },            },          },        },      },    },  },}

Persona çözümleme

Etkin persona deterministik olarak seçilir:

1. Ayarlanmışsa /tts persona <id> yerel tercihi.
2. Ayarlanmışsa messages.tts.persona.
3. Persona yok.

Sağlayıcı seçimi açık olan önce çalışacak şekilde yürür:

1. Doğrudan geçersiz kılmalar (CLI, Gateway, Talk, izin verilen TTS yönergeleri).
2. /tts provider <id> yerel tercihi.
3. Etkin personanın provider değeri.
4. messages.tts.provider.
5. Kayıt defteri otomatik seçimi.

Her sağlayıcı denemesi için OpenClaw yapılandırmaları şu sırayla birleştirir:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Güvenilen istek geçersiz kılmaları
4. İzin verilen model tarafından yayımlanmış TTS yönergesi geçersiz kılmaları

Sağlayıcılar persona istemlerini nasıl kullanır

Persona istem alanları (profile, scene, sampleContext, style, accent, pacing, constraints) sağlayıcıdan bağımsızdır. Her sağlayıcı bunları nasıl kullanacağına kendisi karar verir:

Geri dönüş ilkesi

fallbackPolicy, bir personanın denenen sağlayıcı için hiç bağlaması yoksa davranışı kontrol eder:

Tüm TTS isteği yalnızca denenen her sağlayıcı atlandığında veya başarısız olduğunda başarısız olur.

Talk oturumu sağlayıcı seçimi oturum kapsamındadır. Bir Talk istemcisi sağlayıcı kimliklerini, model kimliklerini, ses kimliklerini ve yerel ayarları talk.catalog içinden seçmeli ve bunları Talk oturumu veya devretme isteği üzerinden geçirmelidir. Bir ses oturumu açmak messages.tts değerini veya genel Talk sağlayıcı varsayılanlarını değiştirmemelidir.

Model güdümlü yönergeler

Varsayılan olarak yardımcı, tek bir yanıt için sesi, modeli veya hızı geçersiz kılmak üzere [[tts:...]] yönergeleri ve yalnızca seste görünmesi gereken ifade ipuçları için isteğe bağlı bir [[tts:text]]...[[/tts:text]] bloğu yayımlayabilir:

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

messages.tts.auto "tagged" olduğunda sesi tetiklemek için yönergeler zorunludur. Akış blok teslimi, bitişik bloklara bölünmüş olsa bile, kanal bunları görmeden önce yönergeleri görünür metinden çıkarır.

modelOverrides.allowProvider: true olmadığı sürece provider=... yok sayılır. Bir yanıt provider=... bildirdiğinde, bu yönergedeki diğer anahtarlar yalnızca o sağlayıcı tarafından ayrıştırılır; desteklenmeyen anahtarlar çıkarılır ve TTS yönergesi uyarıları olarak raporlanır.

Kullanılabilir yönerge anahtarları:

• provider (kayıtlı sağlayıcı kimliği; allowProvider: true gerektirir)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax ses düzeyi, 0-10)
• pitch (MiniMax tamsayı perde, -12 ile 12 arası; kesirli değerler kırpılır)
• emotion (Volcengine duygu etiketi)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Model geçersiz kılmalarını tamamen devre dışı bırak:

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

Diğer ayarlar yapılandırılabilir kalırken sağlayıcı değiştirmeye izin ver:

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

Eğik çizgi komutları

Tek komut /tts. Discord üzerinde OpenClaw ayrıca /voice kaydeder çünkü /tts yerleşik bir Discord komutudur; metin olarak /tts ... yine de çalışır.

/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>

Davranış notları:

• /tts on, yerel TTS tercihini always olarak yazar; /tts off bunu off olarak yazar.
• /tts chat on|off|default, geçerli sohbet için oturum kapsamlı bir otomatik TTS geçersiz kılması yazar.
• /tts persona <id>, yerel persona tercihini yazar; /tts persona off bunu temizler.
• /tts latest, geçerli oturum transkriptinden en son yardımcı yanıtını okur ve bunu bir kez ses olarak gönderir. Yinelenen ses gönderimlerini bastırmak için oturum girdisinde yalnızca bu yanıtın hash değerini saklar.
• /tts audio, tek seferlik bir sesli yanıt üretir (TTS'yi açmaz).
• limit ve summary, ana yapılandırmada değil yerel tercihlerde saklanır.
• /tts status, en son deneme için geri dönüş tanılarını içerir: Fallback: <primary> -> <used>, Attempts: ... ve deneme başına ayrıntı (provider:outcome(reasonCode) latency).
• /status, TTS etkin olduğunda etkin TTS modunun yanı sıra yapılandırılmış sağlayıcıyı, modeli, sesi ve temizlenmiş özel uç nokta meta verilerini gösterir.

Kullanıcı başına tercihler

Eğik çizgi komutları yerel geçersiz kılmaları prefsPath yoluna yazar. Varsayılan değer ~/.openclaw/settings/tts.json; OPENCLAW_TTS_PREFS ortam değişkeni veya messages.tts.prefsPath ile geçersiz kılın.

Bunlar, messages.tts içinden gelen etkili yapılandırmayı ve ilgili ana makine için etkin agents.list[].tts bloğunu geçersiz kılar.

Çıktı biçimleri (sabit)

TTS ses teslimi kanal yeteneği tarafından yönlendirilir. Kanal Plugin'leri, ses tarzı TTS'nin sağlayıcılardan yerel bir voice-note hedefi istemesi mi gerektiğini yoksa normal audio-file sentezini koruyup yalnızca uyumlu çıktıyı ses teslimi için işaretlemesi mi gerektiğini duyurur.

• Sesli not destekli kanallar: sesli not yanıtları Opus'u tercih eder (ElevenLabs'ten opus_48000_64, OpenAI'den opus).
  • 48kHz / 64kbps, sesli mesaj için iyi bir denge sunar.
• Feishu / WhatsApp: bir sesli not yanıtı MP3/WebM/WAV/M4A veya muhtemel başka bir ses dosyası olarak üretildiğinde, kanal Plugin'i yerel sesli mesajı göndermeden önce bunu ffmpeg ile 48kHz Ogg/Opus'a transkodlar. WhatsApp, sonucu Baileys audio payload'ı üzerinden ptt: true ve audio/ogg; codecs=opus ile gönderir. Dönüştürme başarısız olursa Feishu özgün dosyayı ek olarak alır; WhatsApp gönderimi ise uyumsuz bir PTT payload'ı paylaşmak yerine başarısız olur.
• Diğer kanallar: MP3 (ElevenLabs'ten mp3_44100_128, OpenAI'den mp3).
  • 44.1kHz / 128kbps, konuşma netliği için varsayılan dengedir.
• MiniMax: normal ses ekleri için MP3 (speech-2.8-hd modeli, 32kHz örnekleme hızı). Kanal tarafından duyurulan sesli not hedefleri için, kanal transkodlama desteği bildirdiğinde OpenClaw teslimattan önce MiniMax MP3'ü ffmpeg ile 48kHz Opus'a transkodlar.
• Xiaomi MiMo: varsayılan olarak MP3 veya yapılandırıldığında WAV. Kanal tarafından duyurulan sesli not hedefleri için, kanal transkodlama desteği bildirdiğinde OpenClaw teslimattan önce Xiaomi çıktısını ffmpeg ile 48kHz Opus'a transkodlar.
• Yerel CLI: yapılandırılan outputFormat değerini kullanır. Sesli not hedefleri Ogg/Opus'a dönüştürülür ve telefon çıktısı ffmpeg ile ham 16 kHz mono PCM'ye dönüştürülür.
• Google Gemini: Gemini API TTS, ham 24kHz PCM döndürür. OpenClaw bunu ses ekleri için WAV olarak sarmalar, sesli not hedefleri için 48kHz Opus'a transkodlar ve Talk/telefon için PCM'yi doğrudan döndürür.
• Gradium: ses ekleri için WAV, sesli not hedefleri için Opus ve telefon için 8 kHz'de ulaw_8000.
• Inworld: normal ses ekleri için MP3, sesli not hedefleri için yerel OGG_OPUS ve Talk/telefon için 22050 Hz'de ham PCM.
• xAI: varsayılan olarak MP3; responseFormat mp3, wav, pcm, mulaw veya alaw olabilir. OpenClaw, xAI'nin toplu REST TTS uç noktasını kullanır ve tam bir ses eki döndürür; xAI'nin akışlı TTS WebSocket'i bu sağlayıcı yolu tarafından kullanılmaz. Yerel Opus sesli not biçimi bu yol tarafından desteklenmez.
• Microsoft: microsoft.outputFormat değerini kullanır (varsayılan audio-24khz-48kbitrate-mono-mp3).
  • Birlikte gelen aktarım bir outputFormat kabul eder, ancak tüm biçimler hizmetten kullanılamaz.
  • Çıktı biçimi değerleri Microsoft Speech çıktı biçimlerini izler (Ogg/WebM Opus dahil).
  • Telegram sendVoice, OGG/MP3/M4A kabul eder; garantili Opus sesli mesajlarına ihtiyacınız varsa OpenAI/ElevenLabs kullanın.
  • Yapılandırılan Microsoft çıktı biçimi başarısız olursa OpenClaw MP3 ile yeniden dener.

OpenAI/ElevenLabs çıktı biçimleri kanal başına sabittir (yukarıya bakın).

Otomatik TTS davranışı

messages.tts.auto etkinleştirildiğinde OpenClaw:

• Yanıt zaten medya veya bir MEDIA: direktifi içeriyorsa TTS'yi atlar.
• Çok kısa yanıtları atlar (10 karakterin altında).
• Özetler etkinleştirildiğinde uzun yanıtları summaryModel (veya agents.defaults.model.primary) kullanarak özetler.
• Üretilen sesi yanıta ekler.
• mode: "final" içinde, metin akışı tamamlandıktan sonra akışlı son yanıtlar için yine de yalnızca ses TTS gönderir; üretilen medya, normal yanıt ekleriyle aynı kanal medya normalizasyonundan geçer.

Yanıt maxLength değerini aşarsa ve özet kapalıysa (veya özet modeli için API anahtarı yoksa), ses atlanır ve normal metin yanıtı gönderilir.

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

Kanala göre çıktı biçimleri

Sağlayıcıya göre notlar:

• Feishu / WhatsApp dönüştürme: Bir sesli not yanıtı MP3/WebM/WAV/M4A olarak geldiğinde, kanal Plugin'i ffmpeg ile 48 kHz Ogg/Opus'a dönüştürür. WhatsApp, Baileys üzerinden ptt: true ve audio/ogg; codecs=opus ile gönderir. Dönüştürme başarısız olursa: Feishu özgün dosyayı eklemeye geri döner; WhatsApp ise uyumsuz bir PTT yükü göndermek yerine gönderimi başarısız yapar.
• MiniMax / Xiaomi MiMo: Varsayılan MP3 (MiniMax speech-2.8-hd için 32 kHz); sesli not hedefleri için ffmpeg ile 48 kHz Opus'a dönüştürülür.
• Yerel CLI: Yapılandırılmış outputFormat değerini kullanır. Sesli not hedefleri Ogg/Opus'a, telefon çıktısı ise ham 16 kHz mono PCM'ye dönüştürülür.
• Google Gemini: Ham 24 kHz PCM döndürür. OpenClaw ekler için WAV olarak sarar, sesli not hedefleri için 48 kHz Opus'a dönüştürür, Konuşma/telefon için PCM'yi doğrudan döndürür.
• Inworld: MP3 ekleri, yerel OGG_OPUS sesli notu, Konuşma/telefon için ham PCM 22050 Hz.
• xAI: Varsayılan olarak MP3; responseFormat, mp3|wav|pcm|mulaw|alaw olabilir. xAI'nin toplu REST uç noktasını kullanır — akışlı WebSocket TTS kullanılmaz. Yerel Opus sesli not biçimi desteklenmez.
• Microsoft: microsoft.outputFormat kullanır (varsayılan audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice, OGG/MP3/M4A kabul eder; garantili Opus sesli mesajları gerekiyorsa OpenAI/ElevenLabs kullanın. Yapılandırılmış Microsoft biçimi başarısız olursa OpenClaw MP3 ile yeniden dener.

OpenAI ve ElevenLabs çıktı biçimleri, yukarıda listelendiği gibi kanal başına sabittir.

Alan başvurusu

Ajan aracı

tts aracı metni konuşmaya dönüştürür ve yanıt teslimi için bir ses eki döndürür. Feishu, Matrix, Telegram ve WhatsApp üzerinde ses, dosya eki yerine sesli mesaj olarak teslim edilir. Feishu ve WhatsApp, ffmpeg mevcut olduğunda bu yolda Opus olmayan TTS çıktısını dönüştürebilir.

WhatsApp, sesi Baileys üzerinden PTT ses notu olarak gönderir (audio, ptt: true ile) ve görünür metni PTT sesinden ayrı gönderir, çünkü istemciler ses notlarında başlıkları tutarlı biçimde işlemez.

Araç isteğe bağlı channel ve timeoutMs alanlarını kabul eder; timeoutMs, çağrı başına sağlayıcı istek zaman aşımıdır ve milisaniye cinsindendir.

Gateway RPC

Hizmet bağlantıları

• OpenAI metinden konuşmaya kılavuzu
• OpenAI Audio API başvurusu
• Azure Speech REST metinden konuşmaya
• Azure Speech sağlayıcısı
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo konuşma sentezi
• node-edge-tts
• Microsoft Speech çıktı biçimleri
• xAI metinden konuşmaya

İlgili

• Medya genel bakışı
• Müzik oluşturma
• Video oluşturma
• Slash komutları
• Sesli arama plugin'i