文字轉語音

OpenClaw 可以將傳出的回覆轉換為音訊，支援 14 個語音提供者， 並在 Feishu、Matrix、Telegram 和 WhatsApp 上傳送原生語音訊息， 在其他地方傳送音訊附件，並為電話和 Talk 提供 PCM/Ulaw 串流。

TTS 是 Talk 的 stt-tts 模式中負責語音輸出的部分。提供者原生的 realtime Talk 工作階段會在即時提供者內部合成語音， 而不是呼叫此 TTS 路徑；transcription 工作階段則不會合成 助理語音回應。

# 快速開始

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

# 支援的提供者

如果設定了多個提供者，會優先使用選取的提供者， 其他則作為備援選項。自動摘要會使用 summaryModel（或 agents.defaults.model.primary），因此如果你保持摘要啟用， 該提供者也必須完成驗證。

# 設定

TTS 設定位於 ~/.openclaw/openclaw.json 的 messages.tts 下。選擇一個 預設集並調整提供者區塊：

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

# 每個代理的語音覆寫

當某個代理需要使用不同的提供者、語音、模型、persona 或 Auto-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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

若要固定每個代理的人設，請在提供者設定旁設定 agents.list[].tts.persona，它只會覆寫該代理的全域 messages.tts.persona。

自動回覆、/tts audio、/tts status 與 tts 代理工具的優先順序：

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

# 人設

人設是一個穩定的語音身分，可跨提供者以確定性方式套用。它可以偏好某個提供者、定義與提供者無關的提示意圖，並攜帶語音、模型、提示範本、種子與語音設定的提供者專屬繫結。

# 最小人設

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

# 人設解析

啟用中的人設會以確定性方式選取：

1. /tts persona <id> 本機偏好設定，如果已設定。
2. messages.tts.persona，如果已設定。
3. 無人設。

提供者選取會以明確優先的方式執行：

1. 直接覆寫（CLI、Gateway、Talk、允許的 TTS 指令）。
2. /tts provider <id> 本機偏好設定。
3. 啟用中人設的 provider。
4. messages.tts.provider。
5. Registry 自動選取。

對於每次提供者嘗試，OpenClaw 會依下列順序合併設定：

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. 受信任的請求覆寫
4. 允許的模型輸出 TTS 指令覆寫

# 提供者如何使用人設提示

人設提示欄位（profile、scene、sampleContext、style、accent、pacing、constraints）是與提供者無關的。每個提供者會自行決定如何使用它們：

# 後援政策

fallbackPolicy 控制當某個人設對嘗試的提供者沒有繫結時的行為：

整個 TTS 請求只有在每個嘗試的提供者都被略過或失敗時才會失敗。

Talk 工作階段的提供者選取以工作階段為範圍。Talk 用戶端應從 talk.catalog 選擇提供者 ID、模型 ID、語音 ID 與地區設定，並透過 Talk 工作階段或交接請求傳遞它們。開啟語音工作階段不應變更 messages.tts 或全域 Talk 提供者預設值。

# 模型驅動指令

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

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" 時，必須有指令才會觸發音訊。串流區塊遞送會在頻道看到文字之前，先從可見文字中移除指令，即使它們被拆分到相鄰區塊也一樣。

除非 modelOverrides.allowProvider: true，否則會忽略 provider=...。當回覆宣告 provider=... 時，該指令中的其他鍵只會由該提供者解析；不支援的鍵會被移除，並回報為 TTS 指令警告。

可用的指令鍵：

• provider（已註冊的提供者 ID；需要 allowProvider: true）
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• 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>

行為說明：

• /tts on 會將本機 TTS 偏好設定寫為 always；/tts off 會寫為 off。
• /tts chat on|off|default 會為目前聊天寫入工作階段範圍的自動 TTS 覆寫。
• /tts persona <id> 會寫入本機人設偏好設定；/tts persona off 會清除它。
• /tts latest 會從目前工作階段逐字稿讀取最新的助理回覆，並將其作為音訊傳送一次。它只會在工作階段項目上儲存該回覆的雜湊，以抑制重複的語音傳送。
• /tts audio 會產生一次性的音訊回覆（不會開啟 TTS）。
• limit 與 summary 會儲存在本機偏好設定，而不是主要設定中。
• /tts status 會包含最新嘗試的後援診斷資訊：Fallback: <primary> -> <used>、Attempts: ...，以及每次嘗試的詳細資料（provider:outcome(reasonCode) latency）。
• /status 會在啟用 TTS 時顯示啟用中的 TTS 模式，以及已設定的提供者、模型、語音與已清理的自訂端點中繼資料。

# 每位使用者偏好設定

斜線命令會將本機覆寫寫入 prefsPath。預設值是 ~/.openclaw/settings/tts.json；可使用 OPENCLAW_TTS_PREFS 環境變數或 messages.tts.prefsPath 覆寫。

這些會覆寫 messages.tts 加上該主機啟用中 agents.list[].tts 區塊所產生的有效設定。

# 輸出格式（固定）

TTS 語音遞送由頻道能力驅動。頻道 Plugin 會宣告語音樣式 TTS 是否應要求提供者提供原生 voice-note 目標，或保留一般 audio-file 合成，並只為語音遞送標記相容輸出。

• 支援語音備忘訊息的頻道：語音備忘訊息回覆優先使用 Opus（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。
  • 48kHz / 64kbps 是語音訊息的良好折衷。
• Feishu / WhatsApp：當語音備忘訊息回覆產生為 MP3/WebM/WAV/M4A 或其他可能的音訊檔案時，頻道 Plugin 會先用 ffmpeg 將其轉碼為 48kHz Ogg/Opus，再傳送原生語音訊息。WhatsApp 會透過 Baileys audio 承載傳送 結果，並設定 ptt: true 與 audio/ogg; codecs=opus。如果轉換失敗，Feishu 會收到原始 檔案作為附件；WhatsApp 傳送會失敗，而不是發布不相容的 PTT 承載。
• BlueBubbles：讓提供者合成保持在一般音訊檔案路徑；MP3 和 CAF 輸出會標記為用於 iMessage 語音備忘錄傳遞。
• 其他頻道：MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。
  • 44.1kHz / 128kbps 是語音清晰度的預設平衡。
• MiniMax：一般音訊附件使用 MP3（speech-2.8-hd 模型，32kHz 取樣率）。對於頻道宣告的語音備忘訊息目標，當頻道宣告支援轉碼時，OpenClaw 會在傳遞前用 ffmpeg 將 MiniMax MP3 轉碼為 48kHz Opus。
• Xiaomi MiMo：預設使用 MP3，或在設定時使用 WAV。對於頻道宣告的語音備忘訊息目標，當頻道宣告支援轉碼時，OpenClaw 會在傳遞前用 ffmpeg 將 Xiaomi 輸出轉碼為 48kHz Opus。
• 本機 CLI：使用設定的 outputFormat。語音備忘訊息目標會 轉換為 Ogg/Opus，電話語音輸出會用 ffmpeg 轉換為原始 16 kHz 單聲道 PCM。
• Google Gemini：Gemini API TTS 會回傳原始 24kHz PCM。OpenClaw 會將其包裝為 WAV 用於音訊附件、轉碼為 48kHz Opus 用於語音備忘訊息目標，並直接回傳 PCM 用於 Talk/電話語音。
• Gradium：音訊附件使用 WAV，語音備忘訊息目標使用 Opus，電話語音使用 8 kHz 的 ulaw_8000。
• Inworld：一般音訊附件使用 MP3，語音備忘訊息目標使用原生 OGG_OPUS，Talk/電話語音使用 22050 Hz 的原始 PCM。
• xAI：預設使用 MP3；responseFormat 可以是 mp3、wav、pcm、mulaw 或 alaw。OpenClaw 使用 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 重試。

OpenAI/ElevenLabs 輸出格式依頻道固定（見上方）。

# 自動 TTS 行為

啟用 messages.tts.auto 時，OpenClaw 會：

• 如果回覆已包含媒體或 MEDIA: 指令，則略過 TTS。
• 略過非常短的回覆（少於 10 個字元）。
• 在啟用摘要時，使用 summaryModel（或 agents.defaults.model.primary）摘要長回覆。
• 將產生的音訊附加到回覆。
• 在 mode: "final" 中，串流最終回覆的文字串流完成後，仍會傳送僅含音訊的 TTS； 產生的媒體會透過與一般回覆附件相同的 頻道媒體正規化流程。

如果回覆超過 maxLength，且摘要已關閉（或摘要模型沒有 API 金鑰）， 則會略過音訊並傳送一般文字回覆。

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

# 各頻道輸出格式

各提供者注意事項：

• Feishu / WhatsApp 轉碼： 當語音訊息回覆以 MP3/WebM/WAV/M4A 送達時，頻道 Plugin 會使用 ffmpeg 轉碼為 48 kHz Ogg/Opus。WhatsApp 透過 Baileys 以 ptt: true 和 audio/ogg; codecs=opus 傳送。如果轉換失敗：Feishu 會退回附加原始檔案；WhatsApp 傳送會失敗，而不是發布不相容的 PTT 承載。
• MiniMax / Xiaomi MiMo： 預設 MP3（MiniMax speech-2.8-hd 為 32 kHz）；透過 ffmpeg 為語音訊息目標轉碼為 48 kHz Opus。
• 本機 CLI： 使用已設定的 outputFormat。語音訊息目標會轉換為 Ogg/Opus，電話語音輸出會轉換為原始 16 kHz 單聲道 PCM。
• Google Gemini： 回傳原始 24 kHz PCM。OpenClaw 會包裝為 WAV 以供附件使用、為語音訊息目標轉碼為 48 kHz Opus，並為交談/電話語音直接回傳 PCM。
• Inworld： MP3 附件、原生 OGG_OPUS 語音訊息、用於交談/電話語音的原始 PCM 22050 Hz。
• xAI： 預設為 MP3；responseFormat 可以是 mp3|wav|pcm|mulaw|alaw。使用 xAI 的批次 REST 端點 — 不使用串流 WebSocket TTS。不支援原生 Opus 語音訊息格式。
• Microsoft： 使用 microsoft.outputFormat（預設 audio-24khz-48kbitrate-mono-mp3）。Telegram sendVoice 接受 OGG/MP3/M4A；如果需要保證 Opus 語音訊息，請使用 OpenAI/ElevenLabs。如果設定的 Microsoft 格式失敗，OpenClaw 會以 MP3 重試。

OpenAI 和 ElevenLabs 輸出格式會依照上方列出的頻道固定。

# 欄位參考

# Agent 工具

tts 工具會將文字轉換為語音，並回傳音訊附件以供回覆傳送。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音訊會以語音訊息而非檔案附件傳送。Feishu 和 WhatsApp 在此路徑上可於 ffmpeg 可用時，將非 Opus 的 TTS 輸出轉碼。

WhatsApp 會透過 Baileys 將音訊作為 PTT 語音備忘錄（帶有 ptt: true 的 audio）傳送，並且會將可見文字與 PTT 音訊分開傳送，因為用戶端並不一致地在語音備忘錄上顯示字幕。

此工具接受選用的 channel 和 timeoutMs 欄位；timeoutMs 是每次呼叫的提供者請求逾時時間，以毫秒為單位。

# Gateway RPC

# 服務連結

• OpenAI 文字轉語音指南
• OpenAI Audio API 參考
• Azure Speech REST 文字轉語音
• Azure Speech 提供者
• ElevenLabs Text to Speech
• ElevenLabs 驗證
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo 語音合成
• node-edge-tts
• Microsoft Speech 輸出格式
• xAI 文字轉語音

# 相關

• 媒體概覽
• 音樂生成
• 影片生成
• 斜線命令
• 語音通話 Plugin