Text-to-speech

OpenClaw 可以透過 14 個語音提供商 將外發回覆轉換為音訊，並在飛書、Matrix、Telegram 和 WhatsApp 上發送原生語音訊息，其他地方則發送音訊附件，並為電話和 Talk 提供 PCM/Ulaw 串流。

TTS 是 Talk 的 stt-tts 模式的語音輸出部分。供應商原生 realtime Talk 會話會在即時供應商內合成語音，而不是呼叫此 TTS 路徑，而 transcription 會話則不會合成助理語音回覆。

快速開始

選擇一個提供商
OpenAI 和 ElevenLabs 是最可靠的託管選項。Microsoft 和 Local CLI 不需要 API 金鑰即可使用。請參閱提供商矩陣以取得完整清單。
設定 API 金鑰
為您的提供商匯出環境變數（例如 OPENAI_API_KEY、 ELEVENLABS_API_KEY）。Microsoft 和 Local CLI 不需要金鑰。

在設定中啟用

設定 messages.tts.auto: "always" 和 messages.tts.provider：

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

在聊天中試用
/tts status 顯示當前狀態。/tts audio Hello from OpenClaw 發送一次性音訊回覆。

支援的提供商

提供商	驗證	備註
Azure 語音	`AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也有 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`）	原生 Ogg/Opus 語音備忘錄輸出和電話功能。
DeepInfra	`DEEPINFRA_API_KEY`	OpenAI 相容的 TTS。預設為 `hexgrad/Kokoro-82M`。
ElevenLabs	`ELEVENLABS_API_KEY` 或 `XI_API_KEY`	語音複製、多語言、透過 `seed` 確定性；串流用於 Discord 語音播放。
Google Gemini	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`	Gemini API 批次 TTS；透過 `promptTemplate: "audio-profile-v1"` 支援 persona。
Gradium	`GRADIUM_API_KEY`	語音備忘錄和電話輸出。
Inworld	`INWORLD_API_KEY`	串流 TTS API。原生 Opus 語音備忘錄和 PCM 電話。
Local CLI	無	執行已設定的本地 TTS 指令。
Microsoft	無	透過 `node-edge-tts` 提供的公開 Edge 神經網路 TTS。盡力而為，無 SLA。
MiniMax	`MINIMAX_API_KEY` (或 Token 方案：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`)	T2A v2 API。預設為 `speech-2.8-hd`。
OpenAI	`OPENAI_API_KEY`	也用於自動摘要；支援 persona `instructions`。
OpenRouter	`OPENROUTER_API_KEY` (可重複使用 `models.providers.openrouter.apiKey`)	預設模型 `hexgrad/kokoro-82m`。
Volcengine	`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY` (舊版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`)	BytePlus Seed Speech HTTP API。
Vydra	`VYDRA_API_KEY`	共用圖片、影片和語音提供商。
xAI	`XAI_API_KEY`	xAI 批次 TTS。不支援原生 Opus 語音備忘錄。
Xiaomi MiMo	`XIAOMI_API_KEY`	透過 Xiaomi 聊天補全使用 MiMo TTS。

如果設定了多個提供商，會優先使用選定的提供商，其他的則作為備選。自動摘要使用 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",
          speakerVoice: "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",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "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}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "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,
          speakerVoice: "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",
          speakerVoiceId: "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",
          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",
        },
      },
    },
  },
}

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

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

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

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

對於小米 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 status 以及 tts 代理工具的優先順序：

messages.tts
啟用的代理 agents.list[].tts
通道覆蓋，當通道支援 channels.<channel>.tts 時
帳號覆蓋，當通道傳遞 channels.<channel>.accounts.<id>.tts 時
此主機的本機 /tts 偏好設定
啟用模型覆蓋時的行內 [[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,
              },
            },
          },
        },
      },
    },
  },
}

人設解析

啟用的人設是透過確定性方式選擇的：

/tts persona <id> 本地偏好設定（若已設定）。
messages.tts.persona（若已設定）。
無人設。

提供者選擇採用明確優先原則：

直接覆寫（CLI、閘道、Talk、允許的 TTS 指令）。
/tts provider <id> 本地偏好設定。
啟用人設的 provider。
messages.tts.provider。
註冊表自動選擇。

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

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

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

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

Google Gemini

將人設提示詞欄位包裝在 Gemini TTS 提示詞結構中，僅當有效的 Google 提供者設定設定了 promptTemplate: "audio-profile-v1" 或 personaPrompt 時。較舊的 audioProfile 和 speakerName 欄位仍會作為 Google 特定的提示詞文字前置。諸如 [whispers] 或 [laughs] 等內嵌音訊標籤會在 [[tts:text]] 區塊內保留於 Gemini 轉錄中；OpenClaw 不會產生這些標籤。

OpenAI

將人設提示詞欄位對應到請求的 instructions 欄位，僅當未設定明確的 OpenAI instructions 時。明確的 instructions 永遠優先。

其他提供者

僅使用 `personas.

.providers.

` 下的特定提供者角色綁定。除非提供者實作了自己的角色提示詞映射，否則角色提示詞欄位會被忽略。

後援政策

fallbackPolicy 控制當角色對嘗試使用的提供者沒有綁定時的行為：

政策	行為
`preserve-persona`	預設。與提供者無關的提示詞欄位保持可用；提供者可以選擇使用或忽略它們。
`provider-defaults`	在該次嘗試的提示詞準備中省略角色；提供者會使用其中性預設值，同時繼續後援至其他提供者。
`fail`	跳過該提供者的嘗試，並帶有 `reasonCode: "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（舊版別名：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> 寫入本機 persona 偏好；/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 進行覆寫。

已儲存的欄位	效果
`auto`	本機自動 TTS 覆寫 (`always`、`off`、…)
`provider`	本機主要提供者覆寫
`persona`	本機 Persona 覆寫
`maxLength`	摘要閾值 (預設 `1500` 個字元)
`summarize`	摘要切換 (預設 `true`)

這些設定會覆寫來自 messages.tts 的有效設定，以及該主機上作用中的 agents.list[].tts 區塊。

輸出格式 (固定)

TTS 語音傳遞是由通道能力驅動的。通道外掛會宣佈語音風格的 TTS 應要求提供者提供原生的 voice-note 目標，還是保持正常的 audio-file 合成，並僅將相容的輸出標記為語音傳遞。

支援語音訊息的通道：語音訊息回覆偏好使用 Opus (來自 ElevenLabs 的 opus_48000_64、來自 OpenAI 的 opus)。
- 48kHz / 64kbps 是不錯的語音訊息取捨。
飛書 / WhatsApp: 當語音訊息回覆以 MP3/WebM/WAV/M4A 或其他可能的音訊檔案形式產生時，頻道外掛會在發送原生語音訊息之前，使用 ffmpeg 將其轉碼為 48kHz Ogg/Opus。WhatsApp 會透過 Baileys audio 載荷發送結果，並附帶 ptt: true 和 audio/ogg; codecs=opus。如果轉換失敗，飛書會將原始檔案作為附件接收；WhatsApp 發送會失敗，而不是發布不相容的 PTT 載荷。
其他頻道: 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 輸出格式是依頻道固定的（見上文）。

Auto-TTS 行為

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

如果回覆已包含結構化媒體，則跳過 TTS。
跳過非常短的回覆（低於 10 個字元）。
當啟用摘要時，會摘要長回覆，使用 summaryModel（或 agents.defaults.model.primary）。
將產生的音訊附加到回覆。
在 mode: "final" 中，仍會在文字串流完成後，針對串流的最終回覆傳送僅含音訊的 TTS；產生的媒體會經過與正常回覆附件相同的頻道媒體正規化處理。

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

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

各頻道的輸出格式

目標	格式
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`，用於電話功能。

各提供者備註：

飛書 / WhatsApp 轉碼： 當語音訊息回覆為 MP3/WebM/WAV/M4A 時，頻道外掛會使用 ffmpeg 將其轉碼為 48 kHz Ogg/Opus。WhatsApp 透過 Baileys 發送，並使用 ptt: true 和 audio/ogg; codecs=opus。如果轉換失敗：飛書會回退為附加原始檔案；WhatsApp 發送會失敗，而不是發布不相容的 PTT 資料。
MiniMax / 小米 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，並直接為 Talk/電話返回 PCM。
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 重試。

OpenAI 和 ElevenLabs 的輸出格式根據上列各頻道固定。

欄位參考

Top-level messages.tts.*

Auto-TTS 模式。inbound 僅在收到入站語音訊息後發送音訊；tagged 僅在回覆包含 [[tts:...]] 指令或 [[tts:text]] 區塊時發送音訊。

舊版切換開關。openclaw doctor --fix 會將其遷移至 auto。

"all" 除了最終回覆外，還包含工具/區塊回覆。

語音供應商 ID。若未設定，OpenClaw 將依註冊表自動選擇順序使用第一個已設定的供應商。舊版 provider: "edge" 會由 openclaw doctor --fix 重寫為 "microsoft"。

來自 personas 的啟用角色 ID。會被正規化為小寫。

穩定的口語身分。欄位：label、description、provider、fallbackPolicy、prompt、`providers.

`。參見角色。

用於自動摘要的廉價模型；預設為 agents.defaults.model.primary。接受 provider/model 或已設定的模型別名。

允許模型發出 TTS 指令。enabled 預設為 true；allowProvider 預設為 false。

依語音供應商 ID 索引的供應商專屬設定。舊版直接區塊（messages.tts.openai、.elevenlabs、.microsoft、.edge）會由 openclaw doctor --fix 重寫；僅提交 `messages.tts.providers.

`。

TTS 輸入字元的硬性上限。若超過，/tts audio 將會失敗。

要求逾時時間，以毫秒為單位。

覆寫本機偏好設定 JSON 路徑 (provider/limit/summary)。預設為 ~/.openclaw/settings/tts.json。

Azure 語音

環境變數： AZURE_SPEECH_KEY、AZURE_SPEECH_API_KEY 或 SPEECH_KEY。

Azure 語音區域（例如 eastus）。環境變數： AZURE_SPEECH_REGION 或 SPEECH_REGION。

可選的 Azure 語音端點覆寫（別名 baseUrl）。

Azure 語音 ShortName。預設值 en-US-JennyNeural。舊版別名： voice。

SSML 語言代碼。預設值 en-US。

用於標準音訊的 Azure X-Microsoft-OutputFormat。預設值 audio-24khz-48kbitrate-mono-mp3。

用於語音備忘輸出的 Azure X-Microsoft-OutputFormat。預設值 ogg-24khz-16bit-mono-opus。

ElevenLabs

會回退到 ELEVENLABS_API_KEY 或 XI_API_KEY。

模型 ID（例如 eleven_multilingual_v2、eleven_v3）。

ElevenLabs 語音 ID。舊版別名：voiceId。

stability、similarityBoost、style（每個 0..1）、useSpeakerBoost（true|false）、speed（0.5..2.0、1.0 = 正常）。

文字正規化模式。

2 字母 ISO 639-1 代碼（例如 en、de）。

整數 0..4294967295 用於盡力確定性。

覆寫 ElevenLabs API 基礎 URL。

Google Gemini

會退回至 GEMINI_API_KEY / GOOGLE_API_KEY。如果省略，TTS 可以在環境變數退回之前重用 models.providers.google.apiKey。

Gemini TTS 模型。預設為 gemini-3.1-flash-tts-preview。

Gemini 預建語音名稱。預設為 Kore。舊版別名：voiceName、voice。

在口語文字之前附加的自然語言風格提示詞。

當您的提示詞使用具名說話者時，在口語文字之前附加的可選說話者標籤。

設定為 audio-profile-v1，將作用中的 persona 提示詞欄位包裝在確定性的 Gemini TTS 提示詞結構中。

附加至模板「導演註記」的 Google 專用額外 persona 提示詞文字。

僅接受 https://generativelanguage.googleapis.com。

Gradium

環境變數：GRADIUM_API_KEY。

預設為 https://api.gradium.ai。

預設為 Emma (YTpq7expH9539ERJ)。舊版別名：voiceId。

Inworld

Inworld 主要選項

環境變數： INWORLD_API_KEY。

預設值 https://api.inworld.ai。

預設值 inworld-tts-1.5-max。也可用： inworld-tts-1.5-mini、 inworld-tts-1-max、 inworld-tts-1。

預設值 Sarah。舊版別名： voiceId。

採樣溫度 0..2。

Local CLI (tts-local-cli)

CLI TTS 的本機可執行檔或命令字串。

命令引數。支援 {{ Text }}、 {{ OutputPath }}、 {{ OutputDir }}、 {{ OutputBase }} 佔位符。

預期的 CLI 輸出格式。預設為 mp3 用於音訊附件。

命令逾時時間（毫秒）。預設 120000。

選用的命令工作目錄。

命令的選用環境變數覆寫。

Microsoft (無 API 金鑰)

允許使用 Microsoft 語音。

Microsoft 神經語音名稱（例如 en-US-MichelleNeural）。舊版別名：voice。

語言代碼（例如 en-US）。

Microsoft 輸出格式。預設為 audio-24khz-48kbitrate-mono-mp3。內建的 Edge 支援傳輸並不支援所有格式。

百分比字串（例如 +10%、-5%）。

在音訊檔案旁寫入 JSON 字幕。

Microsoft 語音請求的 Proxy URL。

請求逾時覆寫（毫秒）。

舊版別名。執行 openclaw doctor --fix 將保存的設定重寫為 providers.microsoft。

MiniMax

回退至 MINIMAX_API_KEY。透過 MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY 或 MINIMAX_CODING_API_KEY 進行 Token Plan 驗證。

預設值 https://api.minimax.io。環境變數：MINIMAX_API_HOST。

預設值 speech-2.8-hd。環境變數：MINIMAX_TTS_MODEL。

預設值 English_expressive_narrator。環境變數：MINIMAX_TTS_VOICE_ID。舊版別名：voiceId。

0.5..2.0。預設值 1.0。

(0, 10]。預設值 1.0。

整數 -12..12。預設值 0。分數值會在發出請求前被截斷。

OpenAI

回退至 OPENAI_API_KEY。

OpenAI TTS 模型 ID（例如 gpt-4o-mini-tts）。

語音名稱（例如 alloy、cedar）。舊版別名：voice。

明確的 OpenAI instructions 欄位。設定後，persona 提示欄位將不會自動對應。

在生成的 OpenAI TTS 欄位之後，合併至 /audio/speech 請求本額外的 JSON 欄位。將此用於 OpenAI 相容端點（例如 Kokoro），這些端點需要供應商專屬金鑰，如 lang；不安全的原型金鑰將被忽略。

覆寫 OpenAI TTS 端點。解析順序：config → OPENAI_TTS_BASE_URL → https://api.openai.com/v1。非預設值將被視為 OpenAI 相容的 TTS 端點，因此接受自訂模型和語音名稱。

OpenRouter

Env: OPENROUTER_API_KEY。可重用 models.providers.openrouter.apiKey。

預設 https://openrouter.ai/api/v1。舊版 https://openrouter.ai/v1 會被標準化。

預設 hexgrad/kokoro-82m。別名：modelId。

預設 af_alloy。舊版別名：voice、voiceId。

預設 mp3。

提供者原生速度覆寫。

Volcengine (BytePlus Seed Speech)

Env: VOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY。

預設 seed-tts-1.0。Env: VOLCENGINE_TTS_RESOURCE_ID。當您的專案具備 TTS 2.0 授權時使用 seed-tts-2.0。

App key 標頭。預設 aGjiRDfUWi。Env: VOLCENGINE_TTS_APP_KEY。

覆寫 Seed Speech TTS HTTP 端點。Env: VOLCENGINE_TTS_BASE_URL。

語音類型。預設 en_female_anna_mars_bigtts。Env: VOLCENGINE_TTS_VOICE。舊版別名：voice。

提供者原生速度比率。

提供者原生情感標籤。

舊版 Volcengine Speech Console 欄位。Env: VOLCENGINE_TTS_APPID、VOLCENGINE_TTS_TOKEN、VOLCENGINE_TTS_CLUSTER（預設 volcano_tts）。

xAI

Env: XAI_API_KEY.

預設 https://api.x.ai/v1。Env: XAI_BASE_URL。

預設 eve。即時語音：ara、eve、leo、rex、sal、una。舊版別名：voiceId。

BCP-47 語言代碼或 auto。預設 en。

預設 mp3。

提供者原生的速度覆寫。

Xiaomi MiMo

環境變數：XIAOMI_API_KEY。

預設值 https://api.xiaomimimo.com/v1。環境變數：XIAOMI_BASE_URL。

預設值 mimo-v2.5-tts。環境變數：XIAOMI_TTS_MODEL。同時支援 mimo-v2-tts 和 mimo-v2.5-tts-voicedesign。

預設人聲模型的預設值 mimo_default。環境變數：XIAOMI_TTS_VOICE。舊版別名：voice。對於 mimo-v2.5-tts-voicedesign 不會發送。

預設值 mp3。環境變數：XIAOMI_TTS_FORMAT。

作為使用者訊息發送的可選自然語言風格指令；不會被朗讀。對於 mimo-v2.5-tts-voicedesign，這是語音設計提示；若省略，OpenClaw 會提供預設值。

代理工具

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

WhatsApp 透過 Baileys 將音訊作為 PTT 語音備忘錄（具有 ptt: true 的 audio）發送，並會單獨發送可見文字，因為客戶端並不會在語音備忘錄上持續顯示字幕。

此工具接受可選的 channel 和 timeoutMs 欄位；timeoutMs 是以毫秒為單位的每次呼叫提供者請求逾時時間。每次呼叫的值會覆蓋 messages.tts.timeoutMs；已配置的 TTS 逾時時間會覆蓋任何由外掛程式建立的提供者預設值。

Gateway RPC

方法	目的
`tts.status`	讀取目前的 TTS 狀態與上次嘗試。
`tts.enable`	將本機自動偏好設定為 `always`。
`tts.disable`	將本機自動偏好設定為 `off`。
`tts.convert`	單次文字轉音訊。
`tts.setProvider`	設定本機提供者偏好。
`tts.setPersona`	設定本機角色偏好。
`tts.providers`	列出已配置的提供者及其狀態。