文字轉語音

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

快速開始

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

​

支援的供應商

​

設定

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

​

個別代理的語音覆寫

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

1. messages.tts
2. 作用中的 agents.list[].tts
3. 頻道覆寫，當該頻道支援 channels.<channel>.tts 時
4. 帳號覆寫，當該頻道傳遞 channels.<channel>.accounts.<id>.tts 時
5. 此主機的本機 /tts 偏好設定
6. 啟用模型驅動指令時的行內 [[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" },
            },
          },
        },
      },
    },
  },
}

​

Persona

​

最小 persona

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

​

完整 persona（與提供者無關的提示）

{
  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 解析

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

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

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

​

提供者如何使用 persona 提示

​

備援政策

​

模型驅動指令

Here you go.

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

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

​

個別使用者偏好設定

​

輸出格式（固定）

• 支援語音備註的通道：語音備註回覆優先使用 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 重試。

​

Auto-TTS 行為

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

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 供 Talk/電話語音使用。
• Inworld： MP3 附件、原生 OGG_OPUS 語音留言、供 Talk/電話語音使用的原始 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 重試。

​

欄位參考

​

Agent 工具

​

Gateway RPC

​

服務連結

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

​

相關

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