Metinden konuşmaya

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

TTS, Talk'ın stt-tts modunun konuşma çıktısı yarısıdır (talk.speak çağrıları da aynı sentez yolunu kullanır). Sağlayıcıya özgü realtime Talk oturumları konuşmayı gerçek zamanlı sağlayıcının içinde sentezler; transcription oturumları ise hiçbir zaman sesli bir asistan yanıtı sentezlemez.

Hızlı başlangıç

{  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, diğerleri ise yedek seçeneklerdir. Otomatik özet summaryModel (veya agents.defaults.model.primary) kullanır; bu nedenle özetleri etkin tutarsanız bu sağlayıcının kimlik doğrulamasının da yapılması gerekir.

Yapılandırma

TTS yapılandırması, ~/.openclaw/openclaw.json içindeki tts altında bulunur. Bir ön ayar seçip sağlayıcı bloğunu uyarlayın. Aşağıda gösterilen speakerVoice/speakerVoiceId alanları standarttır; her sağlayıcının kendi voice/voiceId/ voiceName alan adları eski takma adlar olarak çalışmaya devam eder.

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

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

{tts: {auto: "always",provider: "google",providers: {  google: {    apiKey: "${GEMINI_API_KEY}",    model: "gemini-3.1-flash-tts-preview",    speakerVoice: "Kore",    // İsteğe bağlı doğal dil stil istemleri:    // audioProfile: "Sakin bir podcast sunucusu tonuyla konuş.",    // speakerName: "Alex",  },},},}

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

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

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

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

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

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

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

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

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

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

Xiaomi mimo-v2.5-tts-voicedesign için speakerVoice alanını atlayın ve style değerini ses tasarımı istemi olarak ayarlayın. OpenClaw bu istemi TTS user mesajı olarak gönderir ve voicedesign modeli için audio.voice göndermez.

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

Bir agent'ın farklı bir sağlayıcı, ses, model, kişilik veya otomatik TTS moduyla konuşması gerektiğinde agents.entries.*.tts kullanın. Agent bloğu tts üzerine derin birleştirme uygular; böylece sağlayıcı kimlik bilgileri genel sağlayıcı yapılandırmasında kalabilir:

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

Aracı başına bir personayı sabitlemek için sağlayıcı yapılandırmasının yanında agents.entries.*.tts.persona ayarını yapın — bu ayar yalnızca söz konusu aracı için genel tts.persona ayarını geçersiz kılar.

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

1. tts
2. etkin agents.entries.*.tts
3. kanal channels.<channel>.tts desteklediğinde kanal geçersiz kılması
4. kanal channels.<channel>.accounts.<id>.tts ilettiğinde hesap geçersiz kılması
5. bu ana makineye ait 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ı, tts ile aynı yapıyı kullanır ve önceki katmanların üzerine derin birleştirme uygular; böylece paylaşılan sağlayıcı kimlik bilgileri tts içinde kalabilirken bir kanal veya bot hesabı yalnızca konuşmacı sesini, modeli, personayı ya da otomatik modu değiştirebilir:

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

Personalar

Bir persona, sağlayıcılar arasında belirlenimsel olarak uygulanabilen kararlı bir sözlü kimliktir. Belirli 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 özgü bağlamalar taşıyabilir.

Minimal persona

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

Tam persona (sağlayıcıya özgü şekillendirme)

{  tts: {    auto: "always",    persona: "alfred",    personas: {      alfred: {        label: "Alfred",        description: "Dry, warm British butler narrator.",        provider: "google",        fallbackPolicy: "preserve-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,            },          },        },      },    },  },}

Persona çözümleme

Etkin persona belirlenimsel olarak seçilir:

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

Sağlayıcı seçimi, açık seçimlere öncelik vererek çalışır:

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

OpenClaw, her sağlayıcı denemesinde yapılandırmaları şu sırayla birleştirir:

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

Özel persona şekillendirme

Sağlayıcıdan bağımsız personas.<id>.prompt.* yapılandırması kullanımdan kaldırılmıştır. Doctor bu alanları kaldırır ve konuşma sağlayıcısı bağlantı noktasına yönlendirir. Yerleşik sağlayıcı ayarlarını personas.<id>.providers.<provider> altına yerleştirin (örneğin Google personaPrompt veya OpenAI instructions). Özel şekillendirme için prepareSynthesis(ctx) içeren bir konuşma sağlayıcısı plugini uygulayın ve synthesize() çalışmadan önce ayarlanmış metni, sağlayıcı yapılandırmasını veya geçersiz kılmaları döndürün. Bu yaklaşım, etkileyici istem oluşturmayı istek semantiğinin bilindiği sağlayıcı kodunda tutar.

Geri dönüş politikası

fallbackPolicy, bir personanın denenen sağlayıcı için bağlaması olmadığında davranışı denetler:

TTS isteğinin tamamı yalnızca denenen tüm sağlayıcılar 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 devir isteği üzerinden iletmelidir. Bir ses oturumunun açılması tts ya da genel Talk sağlayıcı varsayılanlarını değiştirmemelidir.

Model güdümlü yönergeler

Varsayılan olarak asistan, 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 etkileyici ipuçları için isteğe bağlı bir [[tts:text]]...[[/tts:text]] bloğu yayımlayabilir:

Buyurun. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](güler) Şarkıyı bir kez daha oku.[[/tts:text]]

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

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

Kullanılabilir yönerge anahtarları:

• provider (kayıtlı sağlayıcı kimliği; allowProvider: true gerektirir)
• speakerVoice / speakerVoiceId (eski diğer adlar: 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 tam sayı perde değeri, −12 ile 12; 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ırakma:

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

Diğer ayarları yapılandırılabilir tutarken sağlayıcı değiştirmeye izin verme:

{ 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 ç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 konumuna yazar; /tts off ise off konumuna 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 dökümündeki en son asistan yanıtını okur ve bir kez ses olarak gönderir. Yinelenen ses gönderimlerini önlemek için oturum girdisinde yalnızca bu yanıtın karmasını saklar.
• /tts audio, tek seferlik bir sesli yanıt oluşturur (TTS'yi etkinleştirmez).
• /tts limit <chars>, 100–4096 aralığını kabul eder (4096, Telegram açıklama/mesaj üst sınırıdır); bu aralığın dışındaki değerler reddedilir.
• limit ve summary, ana yapılandırmada değil yerel tercihlerde saklanır.
• /tts status, son denemeye ait geri dönüş tanılamalarını içerir — Fallback: <primary> -> <used>, Attempts: ... ve deneme başına ayrıntı (provider:outcome(reasonCode) latency).
• /status, TTS etkinleştirildiğinde yapılandırılmış sağlayıcı, model, ses ve temizlenmiş özel uç nokta meta verileriyle birlikte etkin TTS modunu gösterir.

Kullanıcı başına tercihler

Eğik çizgi komutları, yerel geçersiz kılmaları TTS tercihleri yoluna yazar. Varsayılan değer ~/.openclaw/settings/tts.json; bunu OPENCLAW_TTS_PREFS ile geçersiz kılın. Doctor, kullanımdan kaldırılmış genel tts.prefsPath değerini paylaşılan makine durumuna taşır. Gelişmiş çok aracılı kurulumlarda aracılar kasıtlı olarak ayrı tercih depoları kullandığında agents.entries.<id>.tts.prefsPath ayarı yine yapılabilir.

Bunlar, tts ile söz konusu ana makinenin etkin agents.entries.*.tts bloğundan elde edilen etkili yapılandırmayı geçersiz kılar.

Çıktı biçimleri

TTS ses teslimi kanal yetenekleri tarafından yönlendirilir. Kanal pluginleri, ses tarzı TTS'nin sağlayıcılardan yerel bir voice-note hedefi istemesi mi yoksa normal audio-file sentezini sürdürmesi mi gerektiğini ve kanalın yerel olmayan çıktıyı göndermeden önce dönüştürüp dönüştürmediğini bildirir.

Sağlayıcıya özgü notlar:

• Feishu / WhatsApp kod dönüştürme: Sesli not yanıtı MP3/WebM/WAV/M4A veya başka bir olası ses dosyası olarak geldiğinde, kanal Plugin'i yerel sesli mesajı göndermeden önce dosyayı ffmpeg (libopus, 64 kbps) ile 48 kHz Ogg/Opus biçimine dönüştürür. WhatsApp, sonucu ptt: true ve audio/ogg; codecs=opus ile Baileys audio yükü üzerinden gönderir. Kod dönüştürme başarısız olduğunda: Feishu hatayı yakalar ve özgün dosyayı düz bir ek olarak göndermeye geri döner; WhatsApp'ta geri dönüş yoktur, bu nedenle uyumsuz bir PTT yükü yayımlamak yerine gönderimin kendisi başarısız olur.
• MiniMax: Normal ses ekleri için MP3 (speech-2.8-hd modeli, 32 kHz örnekleme hızı); kanalın sesli not desteği bildirdiği hedefler için ffmpeg ile 48 kHz Opus biçimine dönüştürülür.
• Xiaomi MiMo: Varsayılan olarak MP3 veya yapılandırıldığında WAV; kanalın sesli not desteği bildirdiği hedefler için ffmpeg ile 48 kHz Opus biçimine dönüştürülür.
• Yerel CLI: Yapılandırılmış outputFormat değerini kullanır. Sesli not hedefleri Ogg/Opus biçimine, telefon çıktısı ise ffmpeg ile ham 16 kHz mono PCM biçimine dönüştürülür.
• Google Gemini: Ham 24 kHz PCM döndürür. OpenClaw, ses ekleri için bunu WAV olarak sarmalar, sesli not hedefleri için 48 kHz Opus biçimine dönüştürür ve Talk/telefon için doğrudan PCM 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; ses dosyası sentezi, hem arabelleğe alınan hem de akış çıktısı için mp3, wav, pcm, mulaw veya alaw kullanabilir. xAI'ın pcm, mulaw ve alaw çıktıları başlıksız ham ses olduğundan, sesli not hedefleri akış için MP3 ve arabelleğe alınan geri dönüş için MP3 kullanır. Arabelleğe alınan sentez, xAI'ın toplu REST /v1/tts uç noktasını kullanır; textToSpeechStream yerel wss://api.x.ai/v1/tts kullanır. Bu, gerçek zamanlı ses sözleşmesi değildir. Yerel Opus sesli not biçimi desteklenmez.
• Microsoft: microsoft.outputFormat kullanır (varsayılan audio-24khz-48kbitrate-mono-mp3).
  • Paketle birlikte gelen taşıma, bir outputFormat kabul eder ancak hizmette tüm biçimler kullanılamaz.
  • Çıktı biçimi değerleri Microsoft Speech çıktı biçimlerini izler (Ogg/WebM Opus dâhil).
  • Telegram sendVoice, OGG/MP3/M4A kabul eder; Opus sesli mesajlarının garanti edilmesi gerekiyorsa OpenAI/ElevenLabs kullanın.
  • Yapılandırılmış Microsoft çıktı biçimi başarısız olursa OpenClaw MP3 ile yeniden dener.
  • Açık bir ses geçersiz kılması ayarlanmadığında ve varsayılan İngilizce ses kullanıldığında, yanıt metninde CJK karakterleri baskınsa OpenClaw otomatik olarak Çince bir sinirsel sese (zh-CN-XiaoxiaoNeural, zh-CN yerel ayarı) geçer.

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

Otomatik TTS davranışı

tts.auto etkinleştirildiğinde OpenClaw:

• Yanıt zaten yapılandırılmış medya içeriyorsa TTS'yi atlar.
• Çok kısa yanıtları (10 karakterden az) atlar.
• Özetler etkinleştirildiğinde uzun yanıtları summaryModel (veya agents.defaults.model.primary) kullanarak özetler.
• Oluşturulan sesi yanıta ekler.
• mode: "final" içinde, metin akışı tamamlandıktan sonra akışla iletilen son yanıtlar için yine de yalnızca ses içeren TTS gönderir; oluşturulan medya, normal yanıt ekleriyle aynı kanal medya normalleştirmesinden geçer.

Yanıt maxLength değerini aşarsa OpenClaw sesi hiçbir zaman tamamen atlamaz:

• Özet açık (varsayılan) ve bir özet modeli kullanılabiliyorsa: metni yaklaşık maxLength karaktere özetler, ardından özeti sentezler.
• Özet kapalıysa, özetleme başarısız olursa veya özet modeli için API anahtarı yoksa: metni maxLength karaktere kısaltır ve kısaltılmış metni sentezler.

Yanıt -> TTS etkin mi?  hayır -> metni gönder  evet  -> medya içeriyor mu / kısa mı?           evet  -> metni gönder           hayır -> uzunluk > sınır mı?                    hayır -> TTS -> sesi ekle                    evet  -> özet etkin ve kullanılabilir mi?                             hayır -> kısalt -> TTS -> sesi ekle                             evet  -> özetle -> TTS -> sesi ekle

Alan başvurusu

Agent aracı

tts aracı, metni konuşmaya dönüştürür ve yanıtın iletilmesi için bir ses eki döndürür. Feishu, Matrix, Telegram ve WhatsApp'ta ses, dosya eki yerine sesli mesaj olarak iletilir. Feishu ve WhatsApp, ffmpeg kullanılabiliyorsa bu yolda Opus olmayan TTS çıktısının kodunu dönüştürebilir.

WhatsApp, sesi Baileys üzerinden PTT sesli notu olarak gönderir (audio ve ptt: true) ve istemciler sesli notlardaki altyazıları tutarlı biçimde göstermediği için görünür metni PTT sesinden ayrı olarak gönderir.

Araç, isteğe bağlı channel ve timeoutMs alanlarını kabul eder; timeoutMs, çağrı başına milisaniye cinsinden sağlayıcı isteği zaman aşımıdır. Çağrı başına değerler tts.timeoutMs değerini geçersiz kılar; yapılandırılmış TTS zaman aşımları, Plugin tarafından belirlenen tüm sağlayıcı varsayılanlarını geçersiz kılar.

Gateway RPC

Hizmet bağlantıları

• OpenAI metinden sese dönüştürme kılavuzu
• OpenAI Audio API referansı
• Azure Speech REST metinden sese dönüştürme
• Azure Speech sağlayıcısı
• ElevenLabs Metinden Sese Dönüştürme
• ElevenLabs Kimlik Doğrulaması
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo konuşma sentezi
• node-edge-tts
• Microsoft Speech çıkış biçimleri
• xAI metinden sese dönüştürme

İlgili

• Medyaya genel bakış
• Müzik oluşturma
• Video oluşturma
• Eğik çizgi komutları
• Sesli arama plugin'i