跳轉到主要內容
OpenClaw 會透過 14 個語音提供者將外送回覆轉換為音訊: 在 Feishu、Matrix、Telegram 和 WhatsApp 上使用原生語音訊息;在其他地方使用音訊 附件;並為電話與 Talk 提供 PCM/Ulaw 串流。 TTS 是 Talk 的 stt-tts 模式中的語音輸出部分(talk.speak 會呼叫這條 相同的合成路徑)。提供者原生的 realtime Talk 工作階段會改在即時提供者內部 合成語音;transcription 工作階段則從不合成助理語音回覆。

快速開始

1

選擇提供者

OpenAI 和 ElevenLabs 是最可靠的託管選項。Microsoft 和 Local CLI 不需要 API 金鑰即可使用。完整清單請參閱提供者矩陣
2

設定 API 金鑰

匯出你的提供者所需的環境變數(例如 OPENAI_API_KEYELEVENLABS_API_KEY)。Microsoft 和 Local CLI 不需要金鑰。
3

在設定中啟用

設定 messages.tts.auto: "always"messages.tts.provider
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}
4

在聊天中試用

/tts status 會顯示目前狀態。/tts audio Hello from OpenClaw 會傳送一次性的音訊回覆。
Auto-TTS 預設為關閉。當 messages.tts.provider 未設定時, OpenClaw 會依登錄檔自動選擇順序挑選第一個已設定的提供者。 內建的 tts 代理工具僅限明確意圖:一般聊天會保持 文字,除非使用者要求音訊、使用 /tts,或啟用 Auto-TTS/directive speech。

支援的提供者

提供者驗證備註
Azure SpeechAZURE_SPEECH_KEY + AZURE_SPEECH_REGION(也支援 AZURE_SPEECH_API_KEYSPEECH_KEYSPEECH_REGION原生 Ogg/Opus 語音備忘輸出和電話。
DeepInfraDEEPINFRA_API_KEYOpenAI 相容的 TTS。預設為 hexgrad/Kokoro-82M
ElevenLabsELEVENLABS_API_KEYXI_API_KEY語音複製、多語言,可透過 seed 決定性輸出;為 Discord 語音播放提供串流。
Google GeminiGEMINI_API_KEYGOOGLE_API_KEYGemini API 批次 TTS;透過 promptTemplate: "audio-profile-v1" 感知角色。
GradiumGRADIUM_API_KEY語音備忘和電話輸出。
InworldINWORLD_API_KEY串流 TTS API。原生 Opus 語音備忘和 PCM 電話。
Local CLI執行已設定的本機 TTS 命令。
Microsoft透過 node-edge-tts 使用公開 Edge 神經 TTS。盡力而為,無 SLA。
MiniMaxMINIMAX_API_KEY(或 Token Plan:MINIMAX_OAUTH_TOKENMINIMAX_CODE_PLAN_KEYMINIMAX_CODING_API_KEYT2A v2 API。預設為 speech-2.8-hd
OpenAIOPENAI_API_KEY也用於自動摘要;支援角色 instructions
OpenRouterOPENROUTER_API_KEY(可重用 models.providers.openrouter.apiKey預設模型 hexgrad/kokoro-82m
VolcengineVOLCENGINE_TTS_API_KEYBYTEPLUS_SEED_SPEECH_API_KEY(舊版 AppID/token:VOLCENGINE_TTS_APPID/_TOKENBytePlus Seed Speech HTTP API。
VydraVYDRA_API_KEY共享的圖片、影片和語音提供者。
xAIXAI_API_KEYxAI 批次 TTS。支援原生 Opus 語音備忘。
Xiaomi MiMoXIAOMI_API_KEY透過 Xiaomi chat completions 使用 MiMo TTS。
如果已設定多個提供者,會先使用所選提供者,其他提供者則作為 備援選項。自動摘要使用 summaryModel(或 agents.defaults.model.primary),因此若你保留摘要啟用, 該提供者也必須完成驗證。
內建的 Microsoft 提供者會透過 node-edge-tts 使用 Microsoft Edge 的線上神經 TTS 服務。這是一項未發布 SLA 或配額的公開網路服務,請視為盡力而為。舊版提供者 ID edge 會 正規化為 microsoft,且 openclaw doctor --fix 會重寫已保存的 設定;新的設定應一律使用 microsoft

設定

TTS 設定位於 ~/.openclaw/openclaw.jsonmessages.tts 下。選擇一個 預設集並調整提供者區塊。下方顯示的 speakerVoice/speakerVoiceId 欄位是正式欄位;每個提供者自己的 voice/voiceId/ voiceName 欄位名稱仍可作為舊版別名使用。
{
  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",
        },
      },
    },
  },
}
對於 Xiaomi mimo-v2.5-tts-voicedesign,請省略 speakerVoice,並將 style 設為 語音設計提示。OpenClaw 會將該提示作為 TTS user 訊息傳送, 且不會為 voicedesign 模型傳送 audio.voice

每個代理的語音覆寫

當一個代理需要使用不同的提供者、語音、模型、角色或自動 TTS 模式來發聲時,請使用 agents.list[].tts。代理區塊會深度合併到 messages.tts 之上,因此提供者憑證可以保留在全域提供者設定中:
{
  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" },
          },
        },
      },
    ],
  },
}
若要固定每個代理的角色,請將 agents.list[].tts.persona 與提供者設定一起設定,它只會覆寫該代理的全域 messages.tts.persona 自動回覆、/tts audio/tts statustts 代理工具的優先順序:
  1. messages.tts
  2. 啟用中的 agents.list[].tts
  3. 頻道覆寫,當頻道支援 channels.<channel>.tts
  4. 帳戶覆寫,當頻道傳入 channels.<channel>.accounts.<id>.tts
  5. 此主機的本機 /tts 偏好設定
  6. 啟用模型覆寫時的內嵌 [[tts:...]] 指令
頻道和帳戶覆寫使用與 messages.tts 相同的形狀,並深度合併到前面的層級之上,因此共用的提供者憑證可以保留在 messages.tts,而頻道或機器人帳戶只變更說話語音、模型、角色或自動模式:
{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

角色

角色是可在多個提供者之間以決定性方式套用的穩定語音身分。它可以偏好某個提供者、定義與提供者無關的提示意圖,並攜帶語音、模型、提示範本、種子和語音設定的提供者特定繫結。

最小角色

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

完整角色(與提供者無關的提示)

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

角色解析

啟用中的角色會以決定性方式選取:
  1. /tts persona <id> 本機偏好設定,若已設定。
  2. messages.tts.persona,若已設定。
  3. 無角色。
提供者選取會先採用明確設定:
  1. 直接覆寫(命令列介面、閘道、Talk、允許的 TTS 指令)。
  2. /tts provider <id> 本機偏好設定。
  3. 啟用中角色的 provider
  4. messages.tts.provider
  5. 登錄檔自動選取。
每次嘗試提供者時,OpenClaw 會依此順序合併設定:
  1. messages.tts.providers.<id>
  2. messages.tts.personas.<persona>.providers.<id>
  3. 受信任的請求覆寫
  4. 允許的模型輸出 TTS 指令覆寫

提供者如何使用角色提示

角色提示欄位(profilescenesampleContextstyleaccentpacingconstraints)是與提供者無關的。每個提供者會決定如何使用它們:
只有在有效的 Google 提供者設定設為 promptTemplate: "audio-profile-v1"personaPrompt 時,才會將角色提示欄位包裝在 Gemini TTS 提示結構中。較舊的 audioProfilespeakerName 欄位仍會以前置方式加入為 Google 特定提示文字。[[tts:text]] 區塊內的內嵌音訊標籤,例如 [whispers][laughs],會保留在 Gemini 逐字稿內;OpenClaw 不會產生這些標籤。
只有在未設定明確的 OpenAI instructions 時,才會將角色提示欄位對應到請求的 instructions 欄位。明確的 instructions 一律優先。
只使用 personas.<id>.providers.<provider> 底下提供者特定的角色繫結。除非提供者實作自己的角色提示對應,否則會忽略角色提示欄位。

後援政策

當角色對嘗試的提供者沒有繫結時,fallbackPolicy 會控制行為:
政策行為
preserve-persona預設。 與提供者無關的提示欄位會保持可用;提供者可以使用或忽略它們。
provider-defaults該次嘗試的提示準備會省略角色;提供者會使用其中性預設值,同時繼續後援至其他提供者。
failreasonCode: "not_configured"personaBinding: "missing" 跳過該提供者嘗試。仍會嘗試後援提供者。
只有在每個嘗試的提供者都被跳過或失敗時,整個 TTS 請求才會失敗。 Talk 工作階段的提供者選取是以工作階段為範圍。Talk 用戶端應從 talk.catalog 選擇提供者 ID、模型 ID、語音 ID 和語言環境,並透過 Talk 工作階段或交接請求傳遞它們。開啟語音工作階段不應變更 messages.tts 或全域 Talk 提供者預設值。

模型驅動指令

預設情況下,助理可以輸出 [[tts:...]] 指令,以覆寫單次回覆的語音、模型或速度,並可加上選用的 [[tts:text]]...[[/tts:text]] 區塊,用於只應出現在音訊中的表現提示:
Here you go.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
messages.tts.auto"tagged" 時,必須有指令才會觸發音訊。串流區塊傳送會在頻道看到文字前,從可見文字中移除指令,即使指令被分割到相鄰區塊中也是如此。 除非 modelOverrides.allowProvider: true,否則會忽略 provider=...。當回覆宣告 provider=... 時,該指令中的其他鍵只會由該提供者解析;不支援的鍵會被移除,並回報為 TTS 指令警告。 可用的指令鍵:
  • provider(已註冊的提供者 ID;需要 allowProvider: true
  • speakerVoice / speakerVoiceId(舊別名:voicevoiceNamevoice_namegoogle_voicevoiceId
  • model / google_model
  • stabilitysimilarityBooststylespeeduseSpeakerBoost
  • vol / volume(MiniMax 音量,0–10)
  • pitch(MiniMax 整數音高,−12 到 12;小數值會被截斷)
  • emotion(Volcengine 情緒標籤)
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed
完全停用模型覆寫:
{ messages: { tts: { modelOverrides: { enabled: false } } } }
允許切換提供者,同時讓其他旋鈕保持可設定:
{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }

斜線命令

單一命令 /tts。在 Discord 上,OpenClaw 也會註冊 /voice,因為 /tts 是 Discord 內建命令,文字 /tts ... 仍可運作。
/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>
命令需要授權的傳送者(套用允許清單/擁有者規則),並且必須啟用 commands.text 或原生命令註冊。
行為注意事項:
  • /tts on 會將本機 TTS 偏好設定寫入 always/tts off 會將其寫入 off
  • /tts chat on|off|default 會為目前聊天寫入工作階段範圍的自動 TTS 覆寫。
  • /tts persona <id> 會寫入本機角色偏好設定;/tts persona off 會清除它。
  • /tts latest 會從目前工作階段逐字稿讀取最新的助理回覆,並將其以音訊傳送一次。它只會在工作階段項目上儲存該回覆的雜湊,以抑制重複語音傳送。
  • /tts audio 會產生一次性音訊回覆(不會開啟 TTS)。
  • /tts limit <chars> 接受 100–4096(4096 是 Telegram 說明文字/訊息上限);範圍外的值會被拒絕。
  • limitsummary 會儲存在本機偏好設定中,而不是主要設定。
  • /tts status 會包含最新嘗試的後援診斷,包含 Fallback: <primary> -> <used>Attempts: ...,以及每次嘗試的詳細資料(provider:outcome(reasonCode) latency)。
  • /status 會在啟用 TTS 時顯示啟用中的 TTS 模式,以及設定的提供者、模型、語音和經清理的自訂端點中繼資料。

每位使用者的偏好設定

斜線命令會將本機覆寫寫入 prefsPath。預設為 ~/.openclaw/settings/tts.json;可用 OPENCLAW_TTS_PREFS 環境變數或 messages.tts.prefsPath 覆寫。
儲存欄位效果
auto本機自動 TTS 覆寫(alwaysoff、…)
provider本機主要提供者覆寫
persona本機角色覆寫
maxLength摘要/截斷閾值(預設 1500 字元,/tts limit 範圍 100–4096)
summarize摘要切換(預設 true
這些會覆寫該主機上來自 messages.tts 加上啟用中 agents.list[].tts 區塊的有效設定。

輸出格式

TTS 語音傳送由頻道能力驅動。頻道外掛會宣告 語音樣式的 TTS 是否應要求供應商使用原生 voice-note 目標,或是 維持一般的 audio-file 合成,以及頻道是否會在傳送前轉碼 非原生輸出。
目標格式
Feishu / Matrix / Telegram / WhatsApp語音備註回覆優先使用 Opus(ElevenLabs 的 opus_48000_64、OpenAI 的 opus)。48 kHz / 64 kbps 可在清晰度與大小之間取得平衡。
其他頻道MP3(ElevenLabs 的 mp3_44100_128、OpenAI 的 mp3)。44.1 kHz / 128 kbps 是語音的預設平衡點。
Talk / 電話供應商原生 PCM(Inworld 22050 Hz、Google 24 kHz),或 Gradium 用於電話的 ulaw_8000
各供應商注意事項:
  • **Feishu / WhatsApp 轉碼:**當語音備註回覆以 MP3/WebM/WAV/M4A 或其他可能的音訊檔案形式送達時,頻道外掛會在傳送原生語音訊息前,使用 ffmpeglibopus,64 kbps)將其轉碼為 48 kHz Ogg/Opus。WhatsApp 會透過 Baileys audio 酬載傳送結果,並設定 ptt: trueaudio/ogg; codecs=opus。轉碼失敗時:Feishu 會捕捉錯誤,並退回將原始檔案作為一般附件傳送;WhatsApp 沒有備援,因此傳送本身會失敗,而不是張貼不相容的 PTT 酬載。
  • **MiniMax:**一般音訊附件使用 MP3(speech-2.8-hd 模型,32 kHz 取樣率);對頻道宣告的語音備註目標,會使用 ffmpeg 轉碼為 48 kHz Opus。
  • **Xiaomi MiMo:**預設為 MP3,或在設定時使用 WAV;對頻道宣告的語音備註目標,會使用 ffmpeg 轉碼為 48 kHz Opus。
  • **本機命令列介面:**使用已設定的 outputFormat。語音備註目標會轉換為 Ogg/Opus,電話輸出則會使用 ffmpeg 轉換為原始 16 kHz 單聲道 PCM。
  • **Google Gemini:**回傳原始 24 kHz PCM。OpenClaw 會將其包裝為 WAV 供音訊附件使用,對語音備註目標轉碼為 48 kHz Opus,並對 Talk/電話直接回傳 PCM。
  • **Gradium:**音訊附件使用 WAV,語音備註目標使用 Opus,電話使用 8 kHz 的 ulaw_8000
  • **Inworld:**一般音訊附件使用 MP3,語音備註目標使用原生 OGG_OPUS,Talk/電話使用 22050 Hz 的原始 PCM
  • **xAI:**預設為 MP3;responseFormat 可為 mp3wavpcmmulawalaw。使用 xAI 的批次 REST TTS 端點,並回傳完整的音訊附件;此供應商路徑不使用 xAI 的串流 TTS WebSocket。不支援原生 Opus 語音備註格式。
  • **Microsoft:**使用 microsoft.outputFormat(預設 audio-24khz-48kbitrate-mono-mp3)。
    • 內建傳輸接受 outputFormat,但服務並非提供所有格式。
    • 輸出格式值遵循 Microsoft Speech 輸出格式(包括 Ogg/WebM Opus)。
    • Telegram sendVoice 接受 OGG/MP3/M4A;如果需要保證為 Opus 語音訊息,請使用 OpenAI/ElevenLabs。
    • 如果設定的 Microsoft 輸出格式失敗,OpenClaw 會以 MP3 重試。
    • 當未設定明確語音覆寫且使用預設英文語音時,如果回覆文字以 CJK 為主,OpenClaw 會自動切換為中文神經語音(zh-CN-XiaoxiaoNeuralzh-CN 地區設定)。
OpenAI 和 ElevenLabs 的輸出格式會依上述頻道固定。

自動 TTS 行為

啟用 messages.tts.auto 時,OpenClaw 會:
  • 如果回覆已包含結構化媒體,則略過 TTS。
  • 略過非常短的回覆(少於 10 個字元)。
  • 在啟用摘要時,使用 summaryModel(或 agents.defaults.model.primary)摘要長回覆。
  • 將產生的音訊附加到回覆。
  • mode: "final" 中,串流最終回覆的文字串流完成後, 仍會傳送僅音訊的 TTS;產生的媒體會經過與一般回覆附件相同的 頻道媒體正規化。
如果回覆超過 maxLength,OpenClaw 絕不會直接略過音訊:
  • 摘要開啟(預設)且摘要模型可用:將 文字摘要為約 maxLength 個字元,然後合成摘要。
  • 摘要關閉、摘要失敗,或 摘要模型沒有可用 API 金鑰:將文字截斷為 maxLength 個字元,並合成 截斷後的文字。
Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled and available?
                            no  -> truncate -> TTS -> attach audio
                            yes -> summarize -> TTS -> attach audio

欄位參考

auto
"off" | "always" | "inbound" | "tagged"
自動 TTS 模式。inbound 只會在收到傳入語音訊息後傳送音訊;tagged 只會在回覆包含 [[tts:...]] 指令或 [[tts:text]] 區塊時傳送音訊。
enabled
boolean
已棄用
舊版切換選項。openclaw doctor --fix 會將其遷移到 auto
mode
"final" | "all"
預設值:"final"
"all" 除了最終回覆外,還包含工具/區塊回覆。
provider
string
語音供應商 ID。未設定時,OpenClaw 會依登錄自動選取順序使用第一個已設定的供應商。舊版 provider: "edge" 會由 openclaw doctor --fix 重寫為 "microsoft"
persona
string
來自 personas 的作用中 persona ID。會正規化為小寫。
personas.<id>
object
穩定的口語身分。欄位:labeldescriptionproviderfallbackPolicypromptproviders.<provider>。請參閱 Personas
summaryModel
string
用於自動摘要的低成本模型;預設為 agents.defaults.model.primary。接受 provider/model 或已設定的模型別名。
modelOverrides
object
允許模型發出 TTS 指令。enabled 預設為 trueallowProvider 預設為 false
providers.<id>
object
由供應商擁有的設定,以語音供應商 ID 作為索引鍵。舊版直接區塊(messages.tts.openai.elevenlabs.microsoft.edge)會由 openclaw doctor --fix 重寫;只提交 messages.tts.providers.<id>
maxTextLength
number
預設值:"4096"
TTS 輸入字元的硬性上限。/tts audiotts.converttts.speak 超過時會失敗。
timeoutMs
number
預設值:"30000"
請求逾時,單位為毫秒。設定每次呼叫的 timeoutMs(代理工具、閘道)時會優先使用;否則明確設定的 messages.tts.timeoutMs 會優先於任何外掛作者提供的供應商預設值。
prefsPath
string
覆寫本機偏好 JSON 路徑(供應商/限制/摘要)。預設 ~/.openclaw/settings/tts.json
apiKey
string
環境變數:AZURE_SPEECH_KEYAZURE_SPEECH_API_KEYSPEECH_KEY
region
string
Azure Speech 區域(例如 eastus)。環境變數:AZURE_SPEECH_REGIONSPEECH_REGION
endpoint
string
選用的 Azure Speech 端點覆寫(別名 baseUrl)。
speakerVoice
string
Azure 語音 ShortName。預設 en-US-JennyNeural。舊版別名:voice
lang
string
SSML 語言代碼。預設 en-US
outputFormat
string
標準音訊的 Azure X-Microsoft-OutputFormat。預設 audio-24khz-48kbitrate-mono-mp3
voiceNoteOutputFormat
string
語音備註輸出的 Azure X-Microsoft-OutputFormat。預設 ogg-24khz-16bit-mono-opus
apiKey
string
退回使用 ELEVENLABS_API_KEYXI_API_KEY
model
string
模型 ID。預設 eleven_multilingual_v2。舊版 ID eleven_turbo_v2_5/eleven_turbo_v2 會正規化為對應的 flash 模型。
speakerVoiceId
string
ElevenLabs 語音 ID。預設 pMsXgVXv3BLzUgSXRplE。舊版別名:voiceId
voiceSettings
object
stabilitysimilarityBooststyle(各為 0..1,預設 0.5/0.75/0)、useSpeakerBoosttrue|false,預設 true)、speed0.5..2.0,預設 1.0)。
applyTextNormalization
"auto" | "on" | "off"
文字正規化模式。
languageCode
string
2 字母 ISO 639-1(例如 ende)。
seed
number
整數 0..4294967295,用於盡力達成決定性。
baseUrl
string
覆寫 ElevenLabs API 基礎 URL。
apiKey
string
退回使用 GEMINI_API_KEY / GOOGLE_API_KEY。若省略,TTS 可在退回環境變數前重用 models.providers.google.apiKey
model
string
Gemini TTS 模型。預設 gemini-3.1-flash-tts-preview
speakerVoice
string
Gemini 預建語音名稱。預設 Kore。舊版別名:voiceNamevoice
audioProfile
string
在朗讀文字前加上的自然語言風格提示。
speakerName
string
當提示使用具名說話者時,在朗讀文字前加上的選用說話者標籤。
promptTemplate
"audio-profile-v1"
設為 audio-profile-v1,以將作用中的 persona 提示欄位包裝在決定性的 Gemini TTS 提示結構中。
personaPrompt
string
附加到範本 Director’s Notes 的 Google 專用額外 persona 提示文字。
baseUrl
string
只接受 https://generativelanguage.googleapis.com
apiKey
string
環境變數:GRADIUM_API_KEY
baseUrl
string
預設 https://api.gradium.ai
speakerVoiceId
string
預設 Emma(YTpq7expH9539ERJ)。舊版別名:voiceId

Inworld 主要設定

apiKey
string
環境變數:INWORLD_API_KEY
baseUrl
string
預設 https://api.inworld.ai
modelId
string
預設 inworld-tts-1.5-max。另有:inworld-tts-1.5-miniinworld-tts-1-maxinworld-tts-1
speakerVoiceId
string
預設 Sarah。舊版別名:voiceId
temperature
number
取樣溫度 0..2(不含 0)。
command
string
用於命令列介面 TTS 的本機可執行檔或命令字串。
args
string[]
命令引數。支援 {{Text}}{{OutputPath}}、預留位置。</ParamField> <ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>預期的命令列介面輸出格式。音訊附件預設為mp3。</ParamField> <ParamField path="timeoutMs" type="number">命令逾時,以毫秒為單位。預設 120000`。
cwd
string
選用的命令工作目錄。
env
Record<string, string>
命令的選用環境覆寫。
enabled
boolean
預設值:"true"
允許使用 Microsoft 語音。
speakerVoice
string
Microsoft 神經語音名稱 (例如 en-US-MichelleNeural)。舊版別名:voice。如果預設英文語音生效且回覆文字以中日韓文字為主,OpenClaw 會自動切換為 zh-CN-XiaoxiaoNeural
lang
string
語言代碼 (例如 en-US)。
outputFormat
string
Microsoft 輸出格式。預設 audio-24khz-48kbitrate-mono-mp3。隨附的 Edge 支援傳輸不支援所有格式。
rate / pitch / volume
string
百分比字串 (例如 +10%-5%)。
saveSubtitles
boolean
將 JSON 字幕寫入音訊檔旁邊。
proxy
string
Microsoft 語音請求的 Proxy URL。
timeoutMs
number
請求逾時覆寫 (毫秒)。
edge.*
object
已棄用
舊版別名。執行 openclaw doctor --fix,將已保存的設定重寫為 providers.microsoft
apiKey
string
退回使用 MINIMAX_API_KEY。Token Plan 驗證可透過 MINIMAX_OAUTH_TOKENMINIMAX_CODE_PLAN_KEYMINIMAX_CODING_API_KEY
baseUrl
string
預設 https://api.minimax.io。環境變數:MINIMAX_API_HOST
model
string
預設 speech-2.8-hd。環境變數:MINIMAX_TTS_MODEL
speakerVoiceId
string
預設 English_expressive_narrator。環境變數:MINIMAX_TTS_VOICE_ID。舊版別名:voiceId
speed
number
0.5..2.0。預設 1.0
vol
number
(0, 10]。預設 1.0
pitch
number
整數 -12..12。預設 0。小數值會在請求前被截斷。
apiKey
string
退回使用 OPENAI_API_KEY
model
string
OpenAI TTS 模型 ID。預設 gpt-4o-mini-tts
speakerVoice
string
語音名稱 (例如 alloycedar)。預設 coral。舊版別名:voice
instructions
string
明確的 OpenAI instructions 欄位。設定時,人格提示欄位不會自動對應。
extraBody / extra_body
Record<string, unknown>
額外 JSON 欄位,會在產生的 OpenAI TTS 欄位之後合併到 /audio/speech 請求主體。這可用於 Kokoro 等 OpenAI 相容端點,它們需要像 lang 這類供應商特定鍵;不安全的原型鍵會被忽略。
baseUrl
string
覆寫 OpenAI TTS 端點。解析順序:設定 → OPENAI_TTS_BASE_URLhttps://api.openai.com/v1。非預設值會被視為 OpenAI 相容 TTS 端點,因此接受自訂模型與語音名稱,且 speed 會失去其 0.25..4.0 範圍檢查。
apiKey
string
環境變數:OPENROUTER_API_KEY。可重複使用 models.providers.openrouter.apiKey
baseUrl
string
預設 https://openrouter.ai/api/v1。舊版 https://openrouter.ai/v1 會被正規化。
model
string
預設 hexgrad/kokoro-82m。別名:modelId
speakerVoice
string
預設 af_alloy。舊版別名:voicevoiceId
responseFormat
"mp3" | "pcm"
預設 mp3
speed
number
供應商原生速度覆寫。
apiKey
string
環境變數:VOLCENGINE_TTS_API_KEYBYTEPLUS_SEED_SPEECH_API_KEY
resourceId
string
預設 seed-tts-1.0。環境變數:VOLCENGINE_TTS_RESOURCE_ID。當你的專案具備 TTS 2.0 權益時,請使用 seed-tts-2.0
appKey
string
App key 標頭。預設 aGjiRDfUWi。環境變數:VOLCENGINE_TTS_APP_KEY
baseUrl
string
覆寫 Seed Speech TTS HTTP 端點。環境變數:VOLCENGINE_TTS_BASE_URL
speakerVoice
string
語音類型。預設 en_female_anna_mars_bigtts。環境變數:VOLCENGINE_TTS_VOICE。舊版別名:voice
speedRatio
number
供應商原生速度比例,0.2..3
emotion
string
供應商原生情緒標籤。
appId / token / cluster
string
已棄用
舊版 Volcengine Speech Console 欄位。環境變數:VOLCENGINE_TTS_APPIDVOLCENGINE_TTS_TOKENVOLCENGINE_TTS_CLUSTER (預設 volcano_tts)。
apiKey
string
環境變數:XAI_API_KEY
baseUrl
string
預設 https://api.x.ai/v1。環境變數:XAI_BASE_URL
speakerVoiceId
string
預設 eve。即時語音:araeveleorexsaluna。舊版別名:voiceId
language
string
BCP-47 語言代碼或 auto。預設 en
responseFormat
"mp3" | "wav" | "pcm" | "mulaw" | "alaw"
預設 mp3
speed
number
供應商原生速度覆寫,0.7..1.5
apiKey
string
環境變數:XIAOMI_API_KEY
baseUrl
string
預設 https://api.xiaomimimo.com/v1。環境變數:XIAOMI_BASE_URL
model
string
預設 mimo-v2.5-tts。環境變數:XIAOMI_TTS_MODEL。也支援 mimo-v2-ttsmimo-v2.5-tts-voicedesign
speakerVoice
string
預設語音模型預設為 mimo_default。環境變數:XIAOMI_TTS_VOICE。舊版別名:voice。不會為 mimo-v2.5-tts-voicedesign 傳送。
format
"mp3" | "wav"
預設 mp3。環境變數:XIAOMI_TTS_FORMAT
style
string
選用的自然語言風格指令,會作為使用者訊息傳送;不會被朗讀。對於 mimo-v2.5-tts-voicedesign,這是語音設計提示;省略時,OpenClaw 會提供預設值。

Agent 工具

tts 工具會將文字轉換為語音,並回傳音訊附件以供回覆傳送。在 Feishu、Matrix、Telegram 和 WhatsApp 上,音訊會以語音訊息傳送,而不是檔案附件。當 ffmpeg 可用時,Feishu 和 WhatsApp 可在此路徑上將非 Opus 的 TTS 輸出轉碼。 WhatsApp 會透過 Baileys 將音訊作為 PTT 語音記事傳送 (audio 搭配 ptt: true),並將可見文字與 PTT 音訊分開傳送,因為客戶端不一定會穩定顯示語音記事上的字幕。 此工具接受選用的 channeltimeoutMs 欄位;timeoutMs 是每次呼叫的供應商請求逾時,以毫秒為單位。每次呼叫的值會覆寫 messages.tts.timeoutMs;已設定的 TTS 逾時會覆寫任何外掛作者設定的供應商預設值。

閘道 RPC

方法用途
tts.status讀取目前 TTS 狀態與上次嘗試。
tts.enable將本機自動偏好設定為 always
tts.disable將本機自動偏好設定為 off
tts.convert一次性文字 → 音訊。
tts.setProvider設定本機供應商偏好。
tts.personas列出已設定的人格與目前啟用的人格。
tts.setPersona設定本機人格偏好。
tts.providers列出已設定的供應商與狀態。

服務連結

相關