{"repo": "beaverslab/openclaw-docs", "files": {"src/content/docs/zh-Hant/tools/tts.md": {"b75c2de4c45051d95934c46afabc365f0d97ebbf": {"t": 1785595170.1450293, "n": 37443, "h": "420e5c1ea038a11d", "c": "---\nsummary: \"Text-to-speech for outbound replies — providers, personas, slash commands, and per-channel output\"\nread_when:\n  - Enabling text-to-speech for replies\n  - Configuring a TTS provider, fallback chain, or persona\n  - Using /tts commands or directives\ntitle: \"Text-to-speech\"\nsidebarTitle: \"Text to speech (TTS)\"\n---\n\nOpenClaw 可以透過 **14 個語音提供商** 將外發回覆轉換為音訊，\n並在飛書、Matrix、Telegram 和 WhatsApp 上發送原生語音訊息，\n其他地方則發送音訊附件，並為電話和 Talk 提供 PCM/Ulaw 串流。\n\nTTS 是 Talk 的 `stt-tts` 模式的語音輸出部分。供應商原生\n`realtime` Talk 會話會在即時供應商內合成語音，而不是\n呼叫此 TTS 路徑，而 `transcription` 會話則不會合成\n助理語音回覆。\n\n## 快速開始\n\n<Steps>\n  <Step title=\"選擇一個提供商\">\n    OpenAI 和 ElevenLabs 是最可靠的託管選項。Microsoft 和\n    Local CLI 不需要 API 金鑰即可使用。請參閱[提供商矩陣](#supported-providers)\n   以取得完整清單。\n  </Step>\n  <Step title=\"設定 API 金鑰\">\n    為您的提供商匯出環境變數（例如 `OPENAI_API_KEY`、\n    `ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要金鑰。\n  </Step>\n  <Step title=\"在設定中啟用\">\n    設定 `messages.tts.auto: \"always\"` 和 `messages.tts.provider`：\n\n    ```json5\n    {\n      messages: {\n        tts: {\n          auto: \"always\",\n          provider: \"elevenlabs\",\n        },\n      },\n    }\n    ```\n\n  </Step>\n  <Step title=\"在聊天中試用\">\n    `/tts status` 顯示當前狀態。`/tts audio Hello from OpenClaw`\n    發送一次性音訊回覆。\n  </Step>\n</Steps>\n\n<Note>Auto-TTS 預設為**關閉**。當未設定 `messages.tts.provider` 時， OpenClaw 會依照註冊表自動選擇順序挑選第一個已設定的提供商。 內建的 `tts` 代理工具僅用於明確意圖：普通聊天保持文字狀態， 除非使用者要求音訊、使用 `/tts`，或啟用 Auto-TTS/指令語音。</Note>\n\n## 支援的提供商\n\n| 提供商            | 驗證                                                                                                           | 備註                                                                          |\n| ----------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| **Azure 語音**    | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也有 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`）       | 原生 Ogg/Opus 語音備忘錄輸出和電話功能。                                      |\n| **DeepInfra**     | `DEEPINFRA_API_KEY`                                                                                            | OpenAI 相容的 TTS。預設為 `hexgrad/Kokoro-82M`。                              |\n| **ElevenLabs**    | `ELEVENLABS_API_KEY` 或 `XI_API_KEY`                                                                           | 語音複製、多語言、透過 `seed` 確定性；串流用於 Discord 語音播放。             |\n| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`                                                                           | Gemini API 批次 TTS；透過 `promptTemplate: \"audio-profile-v1\"` 支援 persona。 |\n| **Gradium**       | `GRADIUM_API_KEY`                                                                                              | 語音備忘錄和電話輸出。                                                        |\n| **Inworld**       | `INWORLD_API_KEY`                                                                                              | 串流 TTS API。原生 Opus 語音備忘錄和 PCM 電話。                               |\n| **Local CLI**     | 無                                                                                                             | 執行已設定的本地 TTS 指令。                                                   |\n| **Microsoft**     | 無                                                                                                             | 透過 `node-edge-tts` 提供的公開 Edge 神經網路 TTS。盡力而為，無 SLA。         |\n| **MiniMax**       | `MINIMAX_API_KEY` (或 Token 方案：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`)    | T2A v2 API。預設為 `speech-2.8-hd`。                                          |\n| **OpenAI**        | `OPENAI_API_KEY`                                                                                               | 也用於自動摘要；支援 persona `instructions`。                                 |\n| **OpenRouter**    | `OPENROUTER_API_KEY` (可重複使用 `models.providers.openrouter.apiKey`)                                         | 預設模型 `hexgrad/kokoro-82m`。                                               |\n| **Volcengine**    | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY` (舊版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`) | BytePlus Seed Speech HTTP API。                                               |\n| **Vydra**         | `VYDRA_API_KEY`                                                                                                | 共用圖片、影片和語音提供商。                                                  |\n| **xAI**           | `XAI_API_KEY`                                                                                                  | xAI 批次 TTS。不支援原生 Opus 語音備忘錄。                                    |\n| **Xiaomi MiMo**   | `XIAOMI_API_KEY`                                                                                               | 透過 Xiaomi 聊天補全使用 MiMo TTS。                                           |\n\n如果設定了多個提供商，會優先使用選定的提供商，其他的則作為備選。自動摘要使用 `summaryModel` (或\n`agents.defaults.model.primary`)，因此如果您啟用摘要功能，該提供商也必須已通過驗證。\n\n<Warning>內建的 **Microsoft** 提供者透過 `node-edge-tts` 使用 Microsoft Edge 的線上神經網路 TTS 服務。這是一項沒有發布 SLA 或配額的公開網路服務 — 請將其視為盡力而為的服務。舊版提供者 ID `edge` 會被正規化為 `microsoft`，且 `openclaw doctor --fix` 會重寫已持久化的設定；新設定應始終使用 `microsoft`。</Warning>\n\n## 設定\n\nTTS 設定位於 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。選擇一個預設集並調整提供者區塊：\n\n<Tabs>\n  <Tab title=\"Azure 語音\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"azure-speech\",\n      providers: {\n        \"azure-speech\": {\n          apiKey: \"${AZURE_SPEECH_KEY}\",\n          region: \"eastus\",\n          speakerVoice: \"en-US-JennyNeural\",\n          lang: \"en-US\",\n          outputFormat: \"audio-24khz-48kbitrate-mono-mp3\",\n          voiceNoteOutputFormat: \"ogg-24khz-16bit-mono-opus\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"ElevenLabs\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"elevenlabs\",\n      providers: {\n        elevenlabs: {\n          apiKey: \"${ELEVENLABS_API_KEY}\",\n          model: \"eleven_multilingual_v2\",\n          speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Google Gemini\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"google\",\n      providers: {\n        google: {\n          apiKey: \"${GEMINI_API_KEY}\",\n          model: \"gemini-3.1-flash-tts-preview\",\n          speakerVoice: \"Kore\",\n          // Optional natural-language style prompts:\n          // audioProfile: \"Speak in a calm, podcast-host tone.\",\n          // speakerName: \"Alex\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Gradium\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"gradium\",\n      providers: {\n        gradium: {\n          apiKey: \"${GRADIUM_API_KEY}\",\n          speakerVoiceId: \"YTpq7expH9539ERJ\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Inworld\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"inworld\",\n      providers: {\n        inworld: {\n          apiKey: \"${INWORLD_API_KEY}\",\n          modelId: \"inworld-tts-1.5-max\",\n          speakerVoiceId: \"Sarah\",\n          temperature: 0.7,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Local CLI\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"tts-local-cli\",\n      providers: {\n        \"tts-local-cli\": {\n          command: \"say\",\n          args: [\"-o\", \"{{OutputPath}}\", \"{{Text}}\"],\n          outputFormat: \"wav\",\n          timeoutMs: 120000,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Microsoft (無金鑰)\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"microsoft\",\n      providers: {\n        microsoft: {\n          enabled: true,\n          speakerVoice: \"en-US-MichelleNeural\",\n          lang: \"en-US\",\n          outputFormat: \"audio-24khz-48kbitrate-mono-mp3\",\n          rate: \"+0%\",\n          pitch: \"+0%\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"MiniMax\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"minimax\",\n      providers: {\n        minimax: {\n          apiKey: \"${MINIMAX_API_KEY}\",\n          model: \"speech-2.8-hd\",\n          speakerVoiceId: \"English_expressive_narrator\",\n          speed: 1.0,\n          vol: 1.0,\n          pitch: 0,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"OpenAI + ElevenLabs\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"openai\",\n      summaryModel: \"openai/gpt-4.1-mini\",\n      modelOverrides: { enabled: true },\n      providers: {\n        openai: {\n          apiKey: \"${OPENAI_API_KEY}\",\n          model: \"gpt-4o-mini-tts\",\n          speakerVoice: \"alloy\",\n        },\n        elevenlabs: {\n          apiKey: \"${ELEVENLABS_API_KEY}\",\n          model: \"eleven_multilingual_v2\",\n          speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },\n          applyTextNormalization: \"auto\",\n          languageCode: \"en\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"OpenRouter\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"openrouter\",\n      providers: {\n        openrouter: {\n          apiKey: \"${OPENROUTER_API_KEY}\",\n          model: \"hexgrad/kokoro-82m\",\n          speakerVoice: \"af_alloy\",\n          responseFormat: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Volcengine\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"volcengine\",\n      providers: {\n        volcengine: {\n          apiKey: \"${VOLCENGINE_TTS_API_KEY}\",\n          resourceId: \"seed-tts-1.0\",\n          speakerVoice: \"en_female_anna_mars_bigtts\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"xAI\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"xai\",\n      providers: {\n        xai: {\n          apiKey: \"${XAI_API_KEY}\",\n          speakerVoiceId: \"eve\",\n          language: \"en\",\n          responseFormat: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Xiaomi MiMo\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"xiaomi\",\n      providers: {\n        xiaomi: {\n          apiKey: \"${XIAOMI_API_KEY}\",\n          model: \"mimo-v2.5-tts\",\n          speakerVoice: \"mimo_default\",\n          format: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n</Tabs>\n\n對於小米 `mimo-v2.5-tts-voicedesign`，請省略 `speakerVoice` 並將 `style` 設定為\n聲音設計提示詞。OpenClaw 會將該提示詞作為 TTS `user` 訊息發送，\n並且不會針對 voicedesign 模型發送 `audio.voice`。\n\n### 個別代理語音覆蓋\n\n當某個代理應該使用不同的提供商、\n聲音、模型、角色或自動 TTS 模式說話時，請使用 `agents.list[].tts`。代理區塊會對\n`messages.tts` 進行深度合併，因此提供商憑證可以保留在全域提供商設定中：\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"elevenlabs\",\n      providers: {\n        elevenlabs: { apiKey: \"${ELEVENLABS_API_KEY}\", model: \"eleven_multilingual_v2\" },\n      },\n    },\n  },\n  agents: {\n    list: [\n      {\n        id: \"reader\",\n        tts: {\n          providers: {\n            elevenlabs: { speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\" },\n          },\n        },\n      },\n    ],\n  },\n}\n```\n\n若要固定個別代理的角色，請在提供商設定旁設定 `agents.list[].tts.persona` —\n它僅會覆蓋該代理的全域 `messages.tts.persona`。\n\n自動回覆、`/tts audio`、`/tts status` 以及\n`tts` 代理工具的優先順序：\n\n1. `messages.tts`\n2. 啟用的代理 `agents.list[].tts`\n3. 通道覆蓋，當通道支援 `channels.<channel>.tts` 時\n4. 帳號覆蓋，當通道傳遞 `channels.<channel>.accounts.<id>.tts` 時\n5. 此主機的本機 `/tts` 偏好設定\n6. 啟用[模型覆蓋](#model-driven-directives)時的行內 `[[tts:...]]` 指令\n\n通道和帳號覆蓋使用與 `messages.tts` 相同的結構，並\n對先前的層級進行深度合併，因此共享的提供商憑證可以保留在\n`messages.tts` 中，而通道或機器人帳號僅變更說話者聲音、模型、角色\n或自動模式：\n\n```json5\n{\n  messages: {\n    tts: {\n      provider: \"openai\",\n      providers: {\n        openai: { apiKey: \"${OPENAI_API_KEY}\", model: \"gpt-4o-mini-tts\" },\n      },\n    },\n  },\n  channels: {\n    feishu: {\n      accounts: {\n        english: {\n          tts: {\n            providers: {\n              openai: { speakerVoice: \"shimmer\" },\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n## 角色\n\n**角色** 是一個穩定的口述身分，可以跨提供商確定性應用。\n它可以優先選擇一個提供商，定義與提供商無關的提示詞意圖，\n並包含針對聲音、模型、提示詞範本、種子和聲音設定的特定提供商綁定。\n\n### 基本角色\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      persona: \"narrator\",\n      personas: {\n        narrator: {\n          label: \"Narrator\",\n          provider: \"elevenlabs\",\n          providers: {\n            elevenlabs: {\n              speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n              modelId: \"eleven_multilingual_v2\",\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n### 完整人設（與提供者無關的提示詞）\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      persona: \"alfred\",\n      personas: {\n        alfred: {\n          label: \"Alfred\",\n          description: \"Dry, warm British butler narrator.\",\n          provider: \"google\",\n          fallbackPolicy: \"preserve-persona\",\n          prompt: {\n            profile: \"A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.\",\n            scene: \"A quiet late-night study. Close-mic narration for a trusted operator.\",\n            sampleContext: \"The speaker is answering a private technical request with concise confidence and dry warmth.\",\n            style: \"Refined, understated, lightly amused.\",\n            accent: \"British English.\",\n            pacing: \"Measured, with short dramatic pauses.\",\n            constraints: [\"Do not read configuration values aloud.\", \"Do not explain the persona.\"],\n          },\n          providers: {\n            google: {\n              model: \"gemini-3.1-flash-tts-preview\",\n              speakerVoice: \"Algieba\",\n              promptTemplate: \"audio-profile-v1\",\n            },\n            openai: { model: \"gpt-4o-mini-tts\", speakerVoice: \"cedar\" },\n            elevenlabs: {\n              speakerVoiceId: \"voice_id\",\n              modelId: \"eleven_multilingual_v2\",\n              seed: 42,\n              voiceSettings: {\n                stability: 0.65,\n                similarityBoost: 0.8,\n                style: 0.25,\n                useSpeakerBoost: true,\n                speed: 0.95,\n              },\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n### 人設解析\n\n啟用的人設是透過確定性方式選擇的：\n\n1. `/tts persona <id>` 本地偏好設定（若已設定）。\n2. `messages.tts.persona`（若已設定）。\n3. 無人設。\n\n提供者選擇採用明確優先原則：\n\n1. 直接覆寫（CLI、閘道、Talk、允許的 TTS 指令）。\n2. `/tts provider <id>` 本地偏好設定。\n3. 啟用人設的 `provider`。\n4. `messages.tts.provider`。\n5. 註冊表自動選擇。\n\n對於每次提供者嘗試，OpenClaw 會依以下順序合併設定：\n\n1. `messages.tts.providers.<id>`\n2. `messages.tts.personas.<persona>.providers.<id>`\n3. 受信任的請求覆寫\n4. 允許的模型發出 TTS 指令覆寫\n\n### 提供者如何使用人設提示詞\n\n人設提示詞欄位（`profile`、`scene`、`sampleContext`、`style`、`accent`、\n`pacing`、`constraints`）是**與提供者無關的**。每個提供者會自行決定如何使用它們：\n\n<AccordionGroup>\n  <Accordion title=\"Google Gemini\">\n    將人設提示詞欄位包裝在 Gemini TTS 提示詞結構中，**僅當**\n    有效的 Google 提供者設定設定了 `promptTemplate: \"audio-profile-v1\"`\n    或 `personaPrompt` 時。較舊的 `audioProfile` 和 `speakerName` 欄位仍會\n    作為 Google 特定的提示詞文字前置。諸如 `[whispers]` 或 `[laughs]` 等\n    內嵌音訊標籤會在 `[[tts:text]]` 區塊內保留於\n    Gemini 轉錄中；OpenClaw 不會產生這些標籤。\n  </Accordion>\n  <Accordion title=\"OpenAI\">\n    將人設提示詞欄位對應到請求的 `instructions` 欄位，**僅當**\n    未設定明確的 OpenAI `instructions` 時。明確的 `instructions`\n    永遠優先。\n  </Accordion>\n  <Accordion title=\"其他提供者\">\n    僅使用 `personas.<id>.providers.<provider>` 下的特定提供者角色綁定。\n    除非提供者實作了自己的角色提示詞映射，否則角色提示詞欄位會被忽略。\n  </Accordion>\n</AccordionGroup>\n\n### 後援政策\n\n`fallbackPolicy` 控制當角色對嘗試使用的提供者**沒有綁定**時的行為：\n\n| 政策                | 行為                                                                                                           |\n| ------------------- | -------------------------------------------------------------------------------------------------------------- |\n| `preserve-persona`  | **預設。** 與提供者無關的提示詞欄位保持可用；提供者可以選擇使用或忽略它們。                                    |\n| `provider-defaults` | 在該次嘗試的提示詞準備中省略角色；提供者會使用其中性預設值，同時繼續後援至其他提供者。                         |\n| `fail`              | 跳過該提供者的嘗試，並帶有 `reasonCode: \"not_configured\"` 和 `personaBinding: \"missing\"`。仍會嘗試後援提供者。 |\n\n只有當**每一個**嘗試的提供者都被跳過或失敗時，整個 TTS 請求才會失敗。\n\nTalk 會話的提供者選擇是以會話為範圍的。Talk 客戶端應從 `talk.catalog` 中選擇提供者 ID、模型 ID、語音 ID 和語言環境，並透過 Talk 會話或移交請求傳遞它們。開啟語音會話不應變更 `messages.tts` 或全域 Talk 提供者預設值。\n\n## 模型驅動指令\n\n預設情況下，助手**可以**發出 `[[tts:...]]` 指令，以覆蓋單一回覆的語音、模型或速度，外加一個可選的 `[[tts:text]]...[[/tts:text]]` 區塊，用於僅應出現在音訊中的表達提示：\n\n```text\nHere you go.\n\n[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]\n[[tts:text]](laughs) Read the song once more.[[/tts:text]]\n```\n\n當 `messages.tts.auto` 為 `\"tagged\"` 時，**必須要有指令**才能觸發音訊。串流區塊傳遞會在通道看到指令之前，先從可見文字中移除指令，即使是指令分散在相鄰區塊中。\n\n除非 `modelOverrides.allowProvider: true`，否則會忽略 `provider=...`。當回覆宣告 `provider=...` 時，該指令中的其他金鑰僅由該提供者解析；不支援的金鑰會被移除並回報為 TTS 指令警告。\n\n**可用的指令金鑰：**\n\n- `provider`（註冊的提供者 ID；需要 `allowProvider: true`）\n- `speakerVoice` / `speakerVoiceId`（舊版別名：`voice`、`voiceName`、`voice_name`、`google_voice`、`voiceId`）\n- `model` / `google_model`\n- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`\n- `vol` / `volume`（MiniMax 音量，0–10）\n- `pitch`（MiniMax 整數音高，−12 到 12；小數值會被截斷）\n- `emotion`（Volcengine 情緒標籤）\n- `applyTextNormalization`（`auto|on|off`）\n- `languageCode`（ISO 639-1）\n- `seed`\n\n**完全停用模型覆寫：**\n\n```json5\n{ messages: { tts: { modelOverrides: { enabled: false } } } }\n```\n\n**允許切換提供者，同時保持其他設定可配置：**\n\n```json5\n{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }\n```\n\n## 斜線指令\n\n單一指令 `/tts`。在 Discord 上，OpenClaw 也會註冊 `/voice`，因為\n`/tts` 是 Discord 的內建指令 — 文字 `/tts ...` 仍然有效。\n\n```text\n/tts off | on | status\n/tts chat on | off | default\n/tts latest\n/tts provider <id>\n/tts persona <id> | off\n/tts limit <chars>\n/tts summary off\n/tts audio <text>\n```\n\n<Note>指令需要授權的發送者（適用白名單/擁有者規則），並且必須啟用 `commands.text` 或原生指令註冊。</Note>\n\n行為備註：\n\n- `/tts on` 會將本機 TTS 偏好寫入 `always`；`/tts off` 則將其寫入 `off`。\n- `/tts chat on|off|default` 會為目前聊天寫入一個範圍限於會話的自動 TTS 覆寫。\n- `/tts persona <id>` 寫入本機 persona 偏好；`/tts persona off` 則將其清除。\n- `/tts latest` 會從目前會話紀錄中讀取最新的助手回覆，並將其作為音訊發送一次。它只會在會話條目上儲存該回覆的雜湊值，以避免重複發送語音。\n- `/tts audio` 產生一次性音訊回覆（**不**會開啟 TTS）。\n- `limit` 和 `summary` 儲存在 **本機偏好設定** 中，而非主要設定。\n- `/tts status` 包含最新嘗試的後援診斷資訊 — `Fallback: <primary> -> <used>`、`Attempts: ...` 以及每次嘗試的詳細資料 (`provider:outcome(reasonCode) latency`)。\n- `/status` 會在啟用 TTS 時顯示作用中的 TTS 模式，以及已設定的提供者、模型、聲音和經過清理的自訂端點元資料。\n\n## 每位使用者的偏好設定\n\n斜線指令會將本機覆寫值寫入 `prefsPath`。預設值為\n`~/.openclaw/settings/tts.json`；可使用 `OPENCLAW_TTS_PREFS` 環境變數\n或 `messages.tts.prefsPath` 進行覆寫。\n\n| 已儲存的欄位 | 效果                                   |\n| ------------ | -------------------------------------- |\n| `auto`       | 本機自動 TTS 覆寫 (`always`、`off`、…) |\n| `provider`   | 本機主要提供者覆寫                     |\n| `persona`    | 本機 Persona 覆寫                      |\n| `maxLength`  | 摘要閾值 (預設 `1500` 個字元)          |\n| `summarize`  | 摘要切換 (預設 `true`)                 |\n\n這些設定會覆寫來自 `messages.tts` 的有效設定，以及該主機上作用中的\n`agents.list[].tts` 區塊。\n\n## 輸出格式 (固定)\n\nTTS 語音傳遞是由通道能力驅動的。通道外掛會宣佈語音風格的 TTS 應要求提供者提供原生的 `voice-note` 目標，\n還是保持正常的 `audio-file` 合成，並僅將相容的輸出標記為語音傳遞。\n\n- **支援語音訊息的通道**：語音訊息回覆偏好使用 Opus (來自 ElevenLabs 的 `opus_48000_64`、來自 OpenAI 的 `opus`)。\n  - 48kHz / 64kbps 是不錯的語音訊息取捨。\n- **飛書 / WhatsApp**: 當語音訊息回覆以 MP3/WebM/WAV/M4A 或其他可能的音訊檔案形式產生時，頻道外掛會在發送原生語音訊息之前，使用 `ffmpeg` 將其轉碼為 48kHz Ogg/Opus。WhatsApp 會透過 Baileys `audio` 載荷發送結果，並附帶 `ptt: true` 和 `audio/ogg; codecs=opus`。如果轉換失敗，飛書會將原始檔案作為附件接收；WhatsApp 發送會失敗，而不是發布不相容的 PTT 載荷。\n- **其他頻道**: MP3（來自 ElevenLabs 的 `mp3_44100_128`，來自 OpenAI 的 `mp3`）。\n  - 44.1kHz / 128kbps 是語音清晰度的預設平衡值。\n- **MiniMax**: 對於普通音訊附件為 MP3（`speech-2.8-hd` 模型，32kHz 取樣率）。對於頻道宣稱的語音訊息目標，當頻道宣稱支援轉碼時，OpenClaw 會在傳遞前使用 `ffmpeg` 將 MiniMax MP3 轉碼為 48kHz Opus。\n- **Xiaomi MiMo**: 預設為 MP3，或在配置時為 WAV。對於頻道宣稱的語音訊息目標，當頻道宣稱支援轉碼時，OpenClaw 會在傳遞前使用 `ffmpeg` 將 Xiaomi 輸出轉碼為 48kHz Opus。\n- **本機 CLI**: 使用已配置的 `outputFormat`。語音訊息目標會轉換為 Ogg/Opus，而電話輸出會使用 `ffmpeg` 轉換為原始 16 kHz 單聲道 PCM。\n- **Google Gemini**: Gemini API TTS 返回原始 24kHz PCM。OpenClaw 將其包裝為 WAV 用於音訊附件，轉碼為 48kHz Opus 用於語音訊息目標，並直接返回 PCM 用於 Talk/電話。\n- **Gradium**: 音訊附件為 WAV，語音訊息目標為 Opus，電話為 8 kHz 的 `ulaw_8000`。\n- **Inworld**: 普通音訊附件為 MP3，語音訊息目標為原生 `OGG_OPUS`，Talk/電話為 22050 Hz 的原始 `PCM`。\n- **xAI**：預設為 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端點並傳回完整的音訊附件；此提供者路徑不使用 xAI 的串流 TTS WebSocket。此路徑不支援原生 Opus 語音訊息格式。\n- **Microsoft**：使用 `microsoft.outputFormat`（預設為 `audio-24khz-48kbitrate-mono-mp3`）。\n  - 內建的傳輸接受 `outputFormat`，但並非所有格式都可從該服務取得。\n  - 輸出格式值遵循 Microsoft Speech 輸出格式（包括 Ogg/WebM Opus）。\n  - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果您需要保證的 Opus 語音訊息，請使用 OpenAI/ElevenLabs。\n  - 如果設定的 Microsoft 輸出格式失敗，OpenClaw 會以 MP3 重試。\n\nOpenAI/ElevenLabs 輸出格式是依頻道固定的（見上文）。\n\n## Auto-TTS 行為\n\n當啟用 `messages.tts.auto` 時，OpenClaw 會：\n\n- 如果回覆已包含結構化媒體，則跳過 TTS。\n- 跳過非常短的回覆（低於 10 個字元）。\n- 當啟用摘要時，會摘要長回覆，使用\n  `summaryModel`（或 `agents.defaults.model.primary`）。\n- 將產生的音訊附加到回覆。\n- 在 `mode: \"final\"` 中，仍會在文字串流完成後，針對串流的最終回覆傳送僅含音訊的 TTS；產生的媒體會經過與正常回覆附件相同的頻道媒體正規化處理。\n\n如果回覆超過 `maxLength` 且摘要關閉（或沒有摘要模型的 API 金鑰），則會跳過音訊並傳送正常的文字回覆。\n\n```text\nReply -> TTS enabled?\n  no  -> send text\n  yes -> has media / short?\n          yes -> send text\n          no  -> length > limit?\n                   no  -> TTS -> attach audio\n                   yes -> summary enabled?\n                            no  -> send text\n                            yes -> summarize -> TTS -> attach audio\n```\n\n## 各頻道的輸出格式\n\n| 目標                                  | 格式                                                                                                                                  |\n| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| Feishu / Matrix / Telegram / WhatsApp | 語音訊息回覆偏好 **Opus**（來自 ElevenLabs 的 `opus_48000_64`，來自 OpenAI 的 `opus`）。48 kHz / 64 kbps 在清晰度與大小之間取得平衡。 |\n| 其他頻道                              | **MP3**（來自 ElevenLabs 的 `mp3_44100_128`，來自 OpenAI 的 `mp3`）。語音預設為 44.1 kHz / 128 kbps。                                 |\n| Talk / 電話                           | 提供者原生 **PCM**（Inworld 22050 Hz，Google 24 kHz），或 Gradium 提供的 `ulaw_8000`，用於電話功能。                                  |\n\n各提供者備註：\n\n- **飛書 / WhatsApp 轉碼：** 當語音訊息回覆為 MP3/WebM/WAV/M4A 時，頻道外掛會使用 `ffmpeg` 將其轉碼為 48 kHz Ogg/Opus。WhatsApp 透過 Baileys 發送，並使用 `ptt: true` 和 `audio/ogg; codecs=opus`。如果轉換失敗：飛書會回退為附加原始檔案；WhatsApp 發送會失敗，而不是發布不相容的 PTT 資料。\n- **MiniMax / 小米 MiMo：** 預設為 MP3（MiniMax `speech-2.8-hd` 為 32 kHz）；對於語音訊息目標，會透過 `ffmpeg` 轉碼為 48 kHz Opus。\n- **本機 CLI：** 使用設定的 `outputFormat`。語音訊息目標會轉換為 Ogg/Opus，電話輸出則會轉換為原始 16 kHz 單聲道 PCM。\n- **Google Gemini：** 返回原始 24 kHz PCM。OpenClaw 會將其包裝為 WAV 以作為附件，為語音訊息目標轉碼為 48 kHz Opus，並直接為 Talk/電話返回 PCM。\n- **Inworld：** MP3 附件，原生 `OGG_OPUS` 語音訊息，以及用於 Talk/電話的原始 `PCM` 22050 Hz。\n- **xAI：** 預設為 MP3；`responseFormat` 可能為 `mp3|wav|pcm|mulaw|alaw`。使用 xAI 的批次 REST 端點 — 不使用串流 WebSocket TTS。不支援原生 Opus 語音訊息格式。\n- **Microsoft：** 使用 `microsoft.outputFormat`（預設 `audio-24khz-48kbitrate-mono-mp3`）。Telegram `sendVoice` 接受 OGG/MP3/M4A；如果您需要保證的 Opus 語音訊息，請使用 OpenAI/ElevenLabs。如果設定的 Microsoft 格式失敗，OpenClaw 會使用 MP3 重試。\n\nOpenAI 和 ElevenLabs 的輸出格式根據上列各頻道固定。\n\n## 欄位參考\n\n<AccordionGroup>\n  <Accordion title=\"Top-level messages.tts.*\">\n    <ParamField path=\"auto\" type='\"off\" | \"always\" | \"inbound\" | \"tagged\"'>\n      Auto-TTS 模式。`inbound` 僅在收到入站語音訊息後發送音訊；`tagged` 僅在回覆包含 `[[tts:...]]` 指令或 `[[tts:text]]` 區塊時發送音訊。\n    </ParamField>\n    <ParamField path=\"enabled\" type=\"boolean\" deprecated>\n      舊版切換開關。`openclaw doctor --fix` 會將其遷移至 `auto`。\n    </ParamField>\n    <ParamField path=\"mode\" type='\"final\" | \"all\"' default=\"final\">\n      `\"all\"` 除了最終回覆外，還包含工具/區塊回覆。\n    </ParamField>\n    <ParamField path=\"provider\" type=\"string\">\n      語音供應商 ID。若未設定，OpenClaw 將依註冊表自動選擇順序使用第一個已設定的供應商。舊版 `provider: \"edge\"` 會由 `openclaw doctor --fix` 重寫為 `\"microsoft\"`。\n    </ParamField>\n    <ParamField path=\"persona\" type=\"string\">\n      來自 `personas` 的啟用角色 ID。會被正規化為小寫。\n    </ParamField>\n    <ParamField path=\"personas.<id>\" type=\"object\">\n      穩定的口語身分。欄位：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。參見 [角色](#personas)。\n    </ParamField>\n    <ParamField path=\"summaryModel\" type=\"string\">\n      用於自動摘要的廉價模型；預設為 `agents.defaults.model.primary`。接受 `provider/model` 或已設定的模型別名。\n    </ParamField>\n    <ParamField path=\"modelOverrides\" type=\"object\">\n      允許模型發出 TTS 指令。`enabled` 預設為 `true`；`allowProvider` 預設為 `false`。\n    </ParamField>\n    <ParamField path=\"providers.<id>\" type=\"object\">\n      依語音供應商 ID 索引的供應商專屬設定。舊版直接區塊（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）會由 `openclaw doctor --fix` 重寫；僅提交 `messages.tts.providers.<id>`。\n    </ParamField>\n    <ParamField path=\"maxTextLength\" type=\"number\">\n      TTS 輸入字元的硬性上限。若超過，`/tts audio` 將會失敗。\n    </ParamField>\n    <ParamField path=\"timeoutMs\" type=\"number\">\n      要求逾時時間，以毫秒為單位。\n    </ParamField>\n    <ParamField path=\"prefsPath\" type=\"string\">\n      覆寫本機偏好設定 JSON 路徑 (provider/limit/summary)。預設為 `~/.openclaw/settings/tts.json`。\n    </ParamField>\n  </Accordion>\n\n<Accordion title=\"Azure 語音\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    環境變數： `AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。\n  </ParamField>\n  <ParamField path=\"region\" type=\"string\">\n    Azure 語音區域（例如 `eastus`）。環境變數： `AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。\n  </ParamField>\n  <ParamField path=\"endpoint\" type=\"string\">\n    可選的 Azure 語音端點覆寫（別名 `baseUrl`）。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Azure 語音 ShortName。預設值 `en-US-JennyNeural`。舊版別名： `voice`。\n  </ParamField>\n  <ParamField path=\"lang\" type=\"string\">\n    SSML 語言代碼。預設值 `en-US`。\n  </ParamField>\n  <ParamField path=\"outputFormat\" type=\"string\">\n    用於標準音訊的 Azure `X-Microsoft-OutputFormat`。預設值 `audio-24khz-48kbitrate-mono-mp3`。\n  </ParamField>\n  <ParamField path=\"voiceNoteOutputFormat\" type=\"string\">\n    用於語音備忘輸出的 Azure `X-Microsoft-OutputFormat`。預設值 `ogg-24khz-16bit-mono-opus`。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"ElevenLabs\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    會回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    模型 ID（例如 `eleven_multilingual_v2`、`eleven_v3`）。\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    ElevenLabs 語音 ID。舊版別名：`voiceId`。\n  </ParamField>\n  <ParamField path=\"voiceSettings\" type=\"object\">\n    `stability`、`similarityBoost`、`style`（每個 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`、`1.0` = 正常）。\n  </ParamField>\n  <ParamField path=\"applyTextNormalization\" type='\"auto\" | \"on\" | \"off\"'>\n    文字正規化模式。\n  </ParamField>\n  <ParamField path=\"languageCode\" type=\"string\">\n    2 字母 ISO 639-1 代碼（例如 `en`、`de`）。\n  </ParamField>\n  <ParamField path=\"seed\" type=\"number\">\n    整數 `0..4294967295` 用於盡力確定性。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    覆寫 ElevenLabs API 基礎 URL。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Google Gemini\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    會退回至 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在環境變數退回之前重用 `models.providers.google.apiKey`。\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    Gemini TTS 模型。預設為 `gemini-3.1-flash-tts-preview`。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Gemini 預建語音名稱。預設為 `Kore`。舊版別名：`voiceName`、`voice`。\n  </ParamField>\n  <ParamField path=\"audioProfile\" type=\"string\">\n    在口語文字之前附加的自然語言風格提示詞。\n  </ParamField>\n  <ParamField path=\"speakerName\" type=\"string\">\n    當您的提示詞使用具名說話者時，在口語文字之前附加的可選說話者標籤。\n  </ParamField>\n  <ParamField path=\"promptTemplate\" type='\"audio-profile-v1\"'>\n    設定為 `audio-profile-v1`，將作用中的 persona 提示詞欄位包裝在確定性的 Gemini TTS 提示詞結構中。\n  </ParamField>\n  <ParamField path=\"personaPrompt\" type=\"string\">\n    附加至模板「導演註記」的 Google 專用額外 persona 提示詞文字。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    僅接受 `https://generativelanguage.googleapis.com`。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Gradium\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    環境變數：`GRADIUM_API_KEY`。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    預設為 `https://api.gradium.ai`。\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    預設為 Emma (`YTpq7expH9539ERJ`)。舊版別名：`voiceId`。\n  </ParamField>\n</Accordion>\n\n  <Accordion title=\"Inworld\">\n    ### Inworld 主要選項\n\n    <ParamField path=\"apiKey\" type=\"string\">環境變數： `INWORLD_API_KEY`。</ParamField>\n    <ParamField path=\"baseUrl\" type=\"string\">預設值 `https://api.inworld.ai`。</ParamField>\n    <ParamField path=\"modelId\" type=\"string\">預設值 `inworld-tts-1.5-max`。也可用： `inworld-tts-1.5-mini`、 `inworld-tts-1-max`、 `inworld-tts-1`。</ParamField>\n    <ParamField path=\"speakerVoiceId\" type=\"string\">預設值 `Sarah`。舊版別名： `voiceId`。</ParamField>\n    <ParamField path=\"temperature\" type=\"number\">採樣溫度 `0..2`。</ParamField>\n\n  </Accordion>\n\n<Accordion title=\"Local CLI (tts-local-cli)\">\n  <ParamField path=\"command\" type=\"string\">\n    CLI TTS 的本機可執行檔或命令字串。\n  </ParamField>\n  <ParamField path=\"args\" type=\"string[]\">\n    命令引數。支援 `{{ Text }}`、 `{{ OutputPath }}`、 `{{ OutputDir }}`、 `{{ OutputBase }}` 佔位符。\n  </ParamField>\n  <ParamField path=\"outputFormat\" type='\"mp3\" | \"opus\" | \"wav\"'>\n    預期的 CLI 輸出格式。預設為 `mp3` 用於音訊附件。\n  </ParamField>\n  <ParamField path=\"timeoutMs\" type=\"number\">\n    命令逾時時間（毫秒）。預設 `120000`。\n  </ParamField>\n  <ParamField path=\"cwd\" type=\"string\">\n    選用的命令工作目錄。\n  </ParamField>\n  <ParamField path=\"env\" type=\"Record<string, string>\">\n    命令的選用環境變數覆寫。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Microsoft (無 API 金鑰)\">\n  <ParamField path=\"enabled\" type=\"boolean\" default=\"true\">\n    允許使用 Microsoft 語音。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Microsoft 神經語音名稱（例如 `en-US-MichelleNeural`）。舊版別名：`voice`。\n  </ParamField>\n  <ParamField path=\"lang\" type=\"string\">\n    語言代碼（例如 `en-US`）。\n  </ParamField>\n  <ParamField path=\"outputFormat\" type=\"string\">\n    Microsoft 輸出格式。預設為 `audio-24khz-48kbitrate-mono-mp3`。內建的 Edge 支援傳輸並不支援所有格式。\n  </ParamField>\n  <ParamField path=\"rate / pitch / volume\" type=\"string\">\n    百分比字串（例如 `+10%`、`-5%`）。\n  </ParamField>\n  <ParamField path=\"saveSubtitles\" type=\"boolean\">\n    在音訊檔案旁寫入 JSON 字幕。\n  </ParamField>\n  <ParamField path=\"proxy\" type=\"string\">\n    Microsoft 語音請求的 Proxy URL。\n  </ParamField>\n  <ParamField path=\"timeoutMs\" type=\"number\">\n    請求逾時覆寫（毫秒）。\n  </ParamField>\n  <ParamField path=\"edge.*\" type=\"object\" deprecated>\n    舊版別名。執行 `openclaw doctor --fix` 將保存的設定重寫為 `providers.microsoft`。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"MiniMax\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    回退至 `MINIMAX_API_KEY`。透過 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 進行 Token Plan 驗證。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    預設值 `https://api.minimax.io`。環境變數：`MINIMAX_API_HOST`。\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    預設值 `speech-2.8-hd`。環境變數：`MINIMAX_TTS_MODEL`。\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    預設值 `English_expressive_narrator`。環境變數：`MINIMAX_TTS_VOICE_ID`。舊版別名：`voiceId`。\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    `0.5..2.0`。預設值 `1.0`。\n  </ParamField>\n  <ParamField path=\"vol\" type=\"number\">\n    `(0, 10]`。預設值 `1.0`。\n  </ParamField>\n  <ParamField path=\"pitch\" type=\"number\">\n    整數 `-12..12`。預設值 `0`。分數值會在發出請求前被截斷。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"OpenAI\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    回退至 `OPENAI_API_KEY`。\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    OpenAI TTS 模型 ID（例如 `gpt-4o-mini-tts`）。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    語音名稱（例如 `alloy`、`cedar`）。舊版別名：`voice`。\n  </ParamField>\n  <ParamField path=\"instructions\" type=\"string\">\n    明確的 OpenAI `instructions` 欄位。設定後，persona 提示欄位將**不會**自動對應。\n  </ParamField>\n  <ParamField path=\"extraBody / extra_body\" type=\"Record<string, unknown>\">\n    在生成的 OpenAI TTS 欄位之後，合併至 `/audio/speech` 請求本額外的 JSON 欄位。將此用於 OpenAI 相容端點（例如 Kokoro），這些端點需要供應商專屬金鑰，如 `lang`；不安全的原型金鑰將被忽略。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    覆寫 OpenAI TTS 端點。解析順序：config → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非預設值將被視為 OpenAI 相容的 TTS 端點，因此接受自訂模型和語音名稱。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"OpenRouter\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env: `OPENROUTER_API_KEY`。可重用 `models.providers.openrouter.apiKey`。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    預設 `https://openrouter.ai/api/v1`。舊版 `https://openrouter.ai/v1` 會被標準化。\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    預設 `hexgrad/kokoro-82m`。別名：`modelId`。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    預設 `af_alloy`。舊版別名：`voice`、`voiceId`。\n  </ParamField>\n  <ParamField path=\"responseFormat\" type='\"mp3\" | \"pcm\"'>\n    預設 `mp3`。\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    提供者原生速度覆寫。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Volcengine (BytePlus Seed Speech)\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env: `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。\n  </ParamField>\n  <ParamField path=\"resourceId\" type=\"string\">\n    預設 `seed-tts-1.0`。Env: `VOLCENGINE_TTS_RESOURCE_ID`。當您的專案具備 TTS 2.0 授權時使用 `seed-tts-2.0`。\n  </ParamField>\n  <ParamField path=\"appKey\" type=\"string\">\n    App key 標頭。預設 `aGjiRDfUWi`。Env: `VOLCENGINE_TTS_APP_KEY`。\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    覆寫 Seed Speech TTS HTTP 端點。Env: `VOLCENGINE_TTS_BASE_URL`。\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    語音類型。預設 `en_female_anna_mars_bigtts`。Env: `VOLCENGINE_TTS_VOICE`。舊版別名：`voice`。\n  </ParamField>\n  <ParamField path=\"speedRatio\" type=\"number\">\n    提供者原生速度比率。\n  </ParamField>\n  <ParamField path=\"emotion\" type=\"string\">\n    提供者原生情感標籤。\n  </ParamField>\n  <ParamField path=\"appId / token / cluster\" type=\"string\" deprecated>\n    舊版 Volcengine Speech Console 欄位。Env: `VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（預設 `volcano_tts`）。\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"xAI\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env: `XAI_API_KEY`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    預設 `https://api.x.ai/v1`。Env: `XAI_BASE_URL`。\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    預設 `eve`。即時語音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。舊版別名：`voiceId`。\n  </ParamField>\n  <ParamField path=\"language\" type=\"string\">\n    BCP-47 語言代碼或 `auto`。預設 `en`。\n  </ParamField>\n  <ParamField path=\"responseFormat\" type='\"mp3\" | \"wav\" | \"pcm\" | \"mulaw\" | \"alaw\"'>\n    預設 `mp3`。\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    提供者原生的速度覆寫。\n  </ParamField>\n</Accordion>\n\n  <Accordion title=\"Xiaomi MiMo\">\n    <ParamField path=\"apiKey\" type=\"string\">環境變數：`XIAOMI_API_KEY`。</ParamField>\n    <ParamField path=\"baseUrl\" type=\"string\">預設值 `https://api.xiaomimimo.com/v1`。環境變數：`XIAOMI_BASE_URL`。</ParamField>\n    <ParamField path=\"model\" type=\"string\">預設值 `mimo-v2.5-tts`。環境變數：`XIAOMI_TTS_MODEL`。同時支援 `mimo-v2-tts` 和 `mimo-v2.5-tts-voicedesign`。</ParamField>\n    <ParamField path=\"speakerVoice\" type=\"string\">預設人聲模型的預設值 `mimo_default`。環境變數：`XIAOMI_TTS_VOICE`。舊版別名：`voice`。對於 `mimo-v2.5-tts-voicedesign` 不會發送。</ParamField>\n    <ParamField path=\"format\" type='\"mp3\" | \"wav\"'>預設值 `mp3`。環境變數：`XIAOMI_TTS_FORMAT`。</ParamField>\n    <ParamField path=\"style\" type=\"string\">作為使用者訊息發送的可選自然語言風格指令；不會被朗讀。對於 `mimo-v2.5-tts-voicedesign`，這是語音設計提示；若省略，OpenClaw 會提供預設值。</ParamField>\n  </Accordion>\n</AccordionGroup>\n\n## 代理工具\n\n`tts` 工具將文字轉換為語音並傳回音訊附件以供回覆傳送。在飛書、Matrix、Telegram 和 WhatsApp 上，音訊會作為語音訊息而非檔案附件傳送。當 `ffmpeg` 可用時，飛書和 WhatsApp 可以在此路徑上轉碼非 Opus 的 TTS 輸出。\n\nWhatsApp 透過 Baileys 將音訊作為 PTT 語音備忘錄（具有 `ptt: true` 的 `audio`）發送，並會單獨發送可見文字，因為客戶端並不會在語音備忘錄上持續顯示字幕。\n\n此工具接受可選的 `channel` 和 `timeoutMs` 欄位；`timeoutMs` 是以毫秒為單位的每次呼叫提供者請求逾時時間。每次呼叫的值會覆蓋 `messages.tts.timeoutMs`；已配置的 TTS 逾時時間會覆蓋任何由外掛程式建立的提供者預設值。\n\n## Gateway RPC\n\n| 方法              | 目的                            |\n| ----------------- | ------------------------------- |\n| `tts.status`      | 讀取目前的 TTS 狀態與上次嘗試。 |\n| `tts.enable`      | 將本機自動偏好設定為 `always`。 |\n| `tts.disable`     | 將本機自動偏好設定為 `off`。    |\n| `tts.convert`     | 單次文字轉音訊。                |\n| `tts.setProvider` | 設定本機提供者偏好。            |\n| `tts.setPersona`  | 設定本機角色偏好。              |\n| `tts.providers`   | 列出已配置的提供者及其狀態。    |\n\n## 服務連結\n\n- [OpenAI 文字轉語音指南](https://platform.openai.com/docs/guides/text-to-speech)\n- [OpenAI 音訊 API 參考](https://platform.openai.com/docs/api-reference/audio)\n- [Azure Speech REST 文字轉語音](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)\n- [Azure Speech 提供者](/zh-Hant/providers/azure-speech)\n- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)\n- [ElevenLabs 驗證](https://elevenlabs.io/docs/api-reference/authentication)\n- [Gradium](/zh-Hant/providers/gradium)\n- [Inworld TTS API](https://docs.inworld.ai/tts/tts)\n- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)\n- [Volcengine TTS HTTP API](/zh-Hant/providers/volcengine#text-to-speech)\n- [小米 MiMo 語音合成](/zh-Hant/providers/xiaomi#text-to-speech)\n- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)\n- [Microsoft 語音輸出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)\n- [xAI text to speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)\n\n## 相關\n\n- [媒體概覽](/zh-Hant/tools/media-overview)\n- [音樂生成](/zh-Hant/tools/music-generation)\n- [影片生成](/zh-Hant/tools/video-generation)\n- [斜線指令](/zh-Hant/tools/slash-commands)\n- [語音通話外掛程式](/zh-Hant/plugins/voice-call)\n"}}, "src/content/docs/fr/tools/tts.md": {"b75c2de4c45051d95934c46afabc365f0d97ebbf": {"t": 1785595259.7670379, "n": 52352, "h": "a666aadf4ed189f9", "c": "---\nsummary: \"Synthèse vocale pour les réponses sortantes — providers, personas, commandes slash et sortie par canal\"\nread_when:\n  - Enabling text-to-speech for replies\n  - Configuring a TTS provider, fallback chain, or persona\n  - Using /tts commands or directives\ntitle: \"Synthèse vocale\"\nsidebarTitle: \"Synthèse vocale (TTS)\"\n---\n\nOpenClaw peut convertir les réponses sortantes en audio via **14 fournisseurs de synthèse vocale** et envoyer des messages vocaux natifs sur Feishu, Matrix, Telegram et WhatsApp, des pièces jointes audio partout ailleurs, ainsi que des flux PCM/Ulaw pour la téléphonie et Talk.\n\nLa TTS est la partie sortie vocale du mode `stt-tts` de Talk. Les sessions Talk natives du `realtime` synthétisent la voix à l'intérieur du fournisseur en temps réel au lieu d'appeler ce chemin TTS, tandis que les sessions `transcription` ne synthétisent pas de réponse vocale de l'assistant.\n\n## Quick start\n\n<Steps>\n  <Step title=\"Choisir un fournisseur\"OpenAI>\n    OpenAI et ElevenLabs sont les options hébergées les plus fiables. Microsoft et\n    le Local CLI fonctionnent sans clé d'API. Consultez la [matrice des fournisseurs](#supported-providers)\n    pour la liste complète.\n  </Step>\n  <Step title=\"Définir la clé API\">\n    Exportez la variable d'environnement pour votre fournisseur (par exemple `OPENAI_API_KEY`,\n    `ELEVENLABS_API_KEY`). Microsoft et le CLI local n'ont pas besoin de clé.\n  </Step>\n  <Step title=\"Activer dans la configuration\">\n    Définissez `messages.tts.auto: \"always\"` et `messages.tts.provider` :\n\n    ```json5\n    {\n      messages: {\n        tts: {\n          auto: \"always\",\n          provider: \"elevenlabs\",\n        },\n      },\n    }\n    ```\n\n  </Step>\n  <Step title=\"Essayer dans le chat\">\n    `/tts status` affiche l'état actuel. `/tts audio Hello from OpenClaw`\n    envoie une réponse audio unique.\n  </Step>\n</Steps>\n\n<Note>\n  La TTS automatique est désactivée (**off**) par défaut. Lorsque `messages.tts.provider` n'est pas défini, OpenClaw choisit le premier fournisseur configuré dans l'ordre de sélection automatique du registre. L'outil d'agent intégré `tts` est à intention explicite uniquement : le chat ordinaire reste du texte sauf si l'utilisateur demande de l'audio, utilise `/tts` ou active la TTS automatique/la\n  directive vocale.\n</Note>\n\n## Fournisseurs pris en charge\n\n| Fournisseur       | Auth                                                                                                              | Notes                                                                                            |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| **Azure Speech**  | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (aussi `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`)          | Sortie de notes vocales Ogg/Opus natives et téléphonie.                                          |\n| **DeepInfra**     | `DEEPINFRA_API_KEY`                                                                                               | TTS compatible OpenAI. La valeur par défaut est `hexgrad/Kokoro-82M`.                            |\n| **ElevenLabs**    | `ELEVENLABS_API_KEY` ou `XI_API_KEY`                                                                              | Clonage vocal, multilingue, déterministe via `seed`; diffusé pour la lecture vocale sur Discord. |\n| **Google Gemini** | `GEMINI_API_KEY` ou `GOOGLE_API_KEY`                                                                              | TTS par lots de l'API Gemini; conscient du personnage via `promptTemplate: \"audio-profile-v1\"`.  |\n| **Gradium**       | `GRADIUM_API_KEY`                                                                                                 | Sortie de notes vocales et téléphonie.                                                           |\n| **Inworld**       | `INWORLD_API_KEY`                                                                                                 | API TTS en continu. Note vocale Opus native et téléphonie PCM.                                   |\n| **CLI local**     | aucun                                                                                                             | Exécute une commande TTS locale configurée.                                                      |\n| **Microsoft**     | aucun                                                                                                             | TTS neuronal Edge public via `node-edge-tts`. Best-effort, sans SLA.                             |\n| **MiniMax**       | `MINIMAX_API_KEY` (ou Plan de jeton : `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`)   | T2A v2 API. La valeur par défaut est `speech-2.8-hd`.                                            |\n| **OpenAI**        | `OPENAI_API_KEY`                                                                                                  | Également utilisé pour le résumé automatique; prend en charge le personnage `instructions`.      |\n| **OpenRouter**    | `OPENROUTER_API_KEY` (peut réutiliser `models.providers.openrouter.apiKey`)                                       | Modèle par défaut `hexgrad/kokoro-82m`.                                                          |\n| **Volcengine**    | `VOLCENGINE_TTS_API_KEY` ou `BYTEPLUS_SEED_SPEECH_API_KEY` (AppID/jeton hérité : `VOLCENGINE_TTS_APPID`/`_TOKEN`) | BytePlus Seed Speech HTTP API.                                                                   |\n| **Vydra**         | `VYDRA_API_KEY`                                                                                                   | Fournisseur partagé d'images, de vidéos et de synthèse vocale.                                   |\n| **xAI**           | `XAI_API_KEY`                                                                                                     | Synthèse vocale par lots xAI. La note vocale native Opus n'est **pas** prise en charge.          |\n| **Xiaomi MiMo**   | `XIAOMI_API_KEY`                                                                                                  | Synthèse vocale MiMo via les compléments de chat Xiaomi.                                         |\n\nSi plusieurs providers sont configurés, celui sélectionné est utilisé en premier et les\nautres servent d'options de secours. Le résumé automatique utilise `summaryModel` (ou\n`agents.defaults.model.primary`), donc ce provider doit également être authentifié\nsi vous conservez les résumés activés.\n\n<Warning>\n  Le provider **Microsoft** intégré utilise le service de synthèse vocale neuronale en ligne de Microsoft Edge via `node-edge-tts`. C'est un service web public sans SLA ou quota publié — considérez-le comme au meilleur effort. L'identifiant de provider hérité `edge` est normalisé vers `microsoft` et `openclaw doctor --fix` réécrit la configuration persistée ; les nouvelles configurations doivent\n  toujours utiliser `microsoft`.\n</Warning>\n\n## Configuration\n\nLa configuration TTS se trouve sous `messages.tts` dans `~/.openclaw/openclaw.json`. Choisissez un\npréréglage et adaptez le bloc de provider :\n\n<Tabs>\n  <Tab title=\"Azure Speech\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"azure-speech\",\n      providers: {\n        \"azure-speech\": {\n          apiKey: \"${AZURE_SPEECH_KEY}\",\n          region: \"eastus\",\n          speakerVoice: \"en-US-JennyNeural\",\n          lang: \"en-US\",\n          outputFormat: \"audio-24khz-48kbitrate-mono-mp3\",\n          voiceNoteOutputFormat: \"ogg-24khz-16bit-mono-opus\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"ElevenLabs\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"elevenlabs\",\n      providers: {\n        elevenlabs: {\n          apiKey: \"${ELEVENLABS_API_KEY}\",\n          model: \"eleven_multilingual_v2\",\n          speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Google Gemini\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"google\",\n      providers: {\n        google: {\n          apiKey: \"${GEMINI_API_KEY}\",\n          model: \"gemini-3.1-flash-tts-preview\",\n          speakerVoice: \"Kore\",\n          // Optional natural-language style prompts:\n          // audioProfile: \"Speak in a calm, podcast-host tone.\",\n          // speakerName: \"Alex\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Gradium\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"gradium\",\n      providers: {\n        gradium: {\n          apiKey: \"${GRADIUM_API_KEY}\",\n          speakerVoiceId: \"YTpq7expH9539ERJ\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Inworld\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"inworld\",\n      providers: {\n        inworld: {\n          apiKey: \"${INWORLD_API_KEY}\",\n          modelId: \"inworld-tts-1.5-max\",\n          speakerVoiceId: \"Sarah\",\n          temperature: 0.7,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"CLILocal CLI\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"tts-local-cli\",\n      providers: {\n        \"tts-local-cli\": {\n          command: \"say\",\n          args: [\"-o\", \"{{OutputPath}}\", \"{{Text}}\"],\n          outputFormat: \"wav\",\n          timeoutMs: 120000,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Microsoft (no key)\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"microsoft\",\n      providers: {\n        microsoft: {\n          enabled: true,\n          speakerVoice: \"en-US-MichelleNeural\",\n          lang: \"en-US\",\n          outputFormat: \"audio-24khz-48kbitrate-mono-mp3\",\n          rate: \"+0%\",\n          pitch: \"+0%\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"MiniMaxMiniMax\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"minimax\",\n      providers: {\n        minimax: {\n          apiKey: \"${MINIMAX_API_KEY}\",\n          model: \"speech-2.8-hd\",\n          speakerVoiceId: \"English_expressive_narrator\",\n          speed: 1.0,\n          vol: 1.0,\n          pitch: 0,\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"OpenAIOpenAI + ElevenLabs\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"openai\",\n      summaryModel: \"openai/gpt-4.1-mini\",\n      modelOverrides: { enabled: true },\n      providers: {\n        openai: {\n          apiKey: \"${OPENAI_API_KEY}\",\n          model: \"gpt-4o-mini-tts\",\n          speakerVoice: \"alloy\",\n        },\n        elevenlabs: {\n          apiKey: \"${ELEVENLABS_API_KEY}\",\n          model: \"eleven_multilingual_v2\",\n          speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },\n          applyTextNormalization: \"auto\",\n          languageCode: \"en\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"OpenRouterOpenRouter\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"openrouter\",\n      providers: {\n        openrouter: {\n          apiKey: \"${OPENROUTER_API_KEY}\",\n          model: \"hexgrad/kokoro-82m\",\n          speakerVoice: \"af_alloy\",\n          responseFormat: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"Volcengine\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"volcengine\",\n      providers: {\n        volcengine: {\n          apiKey: \"${VOLCENGINE_TTS_API_KEY}\",\n          resourceId: \"seed-tts-1.0\",\n          speakerVoice: \"en_female_anna_mars_bigtts\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"xAI\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"xai\",\n      providers: {\n        xai: {\n          apiKey: \"${XAI_API_KEY}\",\n          speakerVoiceId: \"eve\",\n          language: \"en\",\n          responseFormat: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n  <Tab title=\"XiaomiXiaomi MiMo\">\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"xiaomi\",\n      providers: {\n        xiaomi: {\n          apiKey: \"${XIAOMI_API_KEY}\",\n          model: \"mimo-v2.5-tts\",\n          speakerVoice: \"mimo_default\",\n          format: \"mp3\",\n        },\n      },\n    },\n  },\n}\n```\n  </Tab>\n</Tabs>\n\nPour le Xiaomi `mimo-v2.5-tts-voicedesign`, omettez `speakerVoice` et définissez `style` sur\nle prompt de conception vocale. OpenClaw envoie ce prompt comme message TTS `user`\net n'envoie pas `audio.voice` pour le modèle voicedesign.\n\n### Remplacements de voix par agent\n\nUtilisez `agents.list[].tts` lorsqu'un agent doit parler avec un fournisseur,\nune voix, un modèle, une personnalité ou un mode TTS automatique différent. Le bloc d'agent effectue une fusion profonde (deep-merge) sur\n`messages.tts`, de sorte que les identifiants du fournisseur peuvent rester dans la configuration globale du fournisseur :\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      provider: \"elevenlabs\",\n      providers: {\n        elevenlabs: { apiKey: \"${ELEVENLABS_API_KEY}\", model: \"eleven_multilingual_v2\" },\n      },\n    },\n  },\n  agents: {\n    list: [\n      {\n        id: \"reader\",\n        tts: {\n          providers: {\n            elevenlabs: { speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\" },\n          },\n        },\n      },\n    ],\n  },\n}\n```\n\nPour figer une personnalité par agent, définissez `agents.list[].tts.persona` avec la configuration du\nfournisseur — elle remplace le `messages.tts.persona` global pour cet agent uniquement.\n\nOrdre de priorité pour les réponses automatiques, `/tts audio`, `/tts status`, et l'\noutil agent `tts` :\n\n1. `messages.tts`\n2. `agents.list[].tts` actif\n3. remplacement de canal (channel), lorsque le canal prend en charge `channels.<channel>.tts`\n4. remplacement de compte, lorsque le canal transmet `channels.<channel>.accounts.<id>.tts`\n5. préférences locales `/tts` pour cet hôte\n6. directives `[[tts:...]]` en ligne lorsque les [remplacements de modèle](#model-driven-directives) sont activés\n\nLes remplacements de canal et de compte utilisent la même structure que `messages.tts` et\nfusionnent profondément (deep-merge) sur les couches précédentes, de sorte que les identifiants partagés du fournisseur peuvent rester dans\n`messages.tts` tandis qu'un canal ou un compte de bot ne change que la voix du locuteur, le modèle, la personnalité\nou le mode automatique :\n\n```json5\n{\n  messages: {\n    tts: {\n      provider: \"openai\",\n      providers: {\n        openai: { apiKey: \"${OPENAI_API_KEY}\", model: \"gpt-4o-mini-tts\" },\n      },\n    },\n  },\n  channels: {\n    feishu: {\n      accounts: {\n        english: {\n          tts: {\n            providers: {\n              openai: { speakerVoice: \"shimmer\" },\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n## Personnalités\n\nUne **persona** est une identité vocale stable qui peut être appliquée de manière déterministe\nsur plusieurs providers. Elle peut préférer un provider, définir une intention de prompt\nneutre vis-à-vis du provider et transporter des liaisons spécifiques au provider pour les voix, les modèles, les modèles de\nprompt, les seeds et les réglages vocaux.\n\n### Persona minimale\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      persona: \"narrator\",\n      personas: {\n        narrator: {\n          label: \"Narrator\",\n          provider: \"elevenlabs\",\n          providers: {\n            elevenlabs: {\n              speakerVoiceId: \"EXAVITQu4vr4xnSDxMaL\",\n              modelId: \"eleven_multilingual_v2\",\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n### Persona complète (prompt neutre vis-à-vis du provider)\n\n```json5\n{\n  messages: {\n    tts: {\n      auto: \"always\",\n      persona: \"alfred\",\n      personas: {\n        alfred: {\n          label: \"Alfred\",\n          description: \"Dry, warm British butler narrator.\",\n          provider: \"google\",\n          fallbackPolicy: \"preserve-persona\",\n          prompt: {\n            profile: \"A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.\",\n            scene: \"A quiet late-night study. Close-mic narration for a trusted operator.\",\n            sampleContext: \"The speaker is answering a private technical request with concise confidence and dry warmth.\",\n            style: \"Refined, understated, lightly amused.\",\n            accent: \"British English.\",\n            pacing: \"Measured, with short dramatic pauses.\",\n            constraints: [\"Do not read configuration values aloud.\", \"Do not explain the persona.\"],\n          },\n          providers: {\n            google: {\n              model: \"gemini-3.1-flash-tts-preview\",\n              speakerVoice: \"Algieba\",\n              promptTemplate: \"audio-profile-v1\",\n            },\n            openai: { model: \"gpt-4o-mini-tts\", speakerVoice: \"cedar\" },\n            elevenlabs: {\n              speakerVoiceId: \"voice_id\",\n              modelId: \"eleven_multilingual_v2\",\n              seed: 42,\n              voiceSettings: {\n                stability: 0.65,\n                similarityBoost: 0.8,\n                style: 0.25,\n                useSpeakerBoost: true,\n                speed: 0.95,\n              },\n            },\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n### Résolution de la persona\n\nLa persona active est sélectionnée de manière déterministe :\n\n1. `/tts persona <id>` préférence locale, si définie.\n2. `messages.tts.persona`, si défini.\n3. Aucune persona.\n\nLa sélection du provider fonctionne par ordre de priorité explicite :\n\n1. Remplacements directs (CLI, passerelle, Talk, directives TTS autorisées).\n2. `/tts provider <id>` préférence locale.\n3. `provider` de la persona active.\n4. `messages.tts.provider`.\n5. Sélection automatique dans le registre.\n\nPour chaque tentative de provider, OpenClaw fusionne les configurations dans cet ordre :\n\n1. `messages.tts.providers.<id>`\n2. `messages.tts.personas.<persona>.providers.<id>`\n3. Remplacements de requête approuvés\n4. Remplacements de directives TTS émises par le modèle autorisés\n\n### Comment les providers utilisent les prompts de persona\n\nLes champs de prompt de persona (`profile`, `scene`, `sampleContext`, `style`, `accent`,\n`pacing`, `constraints`) sont **neutres vis-à-vis du provider**. Chaque provider décide comment\nles utiliser :\n\n<AccordionGroup>\n  <Accordion title=\"Google Gemini\">\n    Enveloppe les champs de prompt de persona dans une structure de prompt TTS Gemini **uniquement lorsque**\n    la configuration effective du provider Google définit `promptTemplate: \"audio-profile-v1\"`\n    ou `personaPrompt`. Les anciens champs `audioProfile` et `speakerName` sont\n    toujours ajoutés en préambule en tant que texte de prompt spécifique à Google. Les balises audio en ligne telles que\n    `[whispers]` ou `[laughs]` à l'intérieur d'un bloc `[[tts:text]]`OpenClaw sont préservées\n    dans la transcription Gemini ; OpenClaw ne génère pas ces balises.\n  </Accordion>\n  <Accordion title=\"OpenAIOpenAI\">\n    Mappe les champs de prompt de persona au champ de demande `instructions`OpenAI **uniquement lorsque**\n    aucun `instructions` OpenAI explicite n'est configuré. Le `instructions` explicite\n    l'emporte toujours.\n  </Accordion>\n  <Accordion title=\"Autres providers\">\n    Utilise uniquement les liaisons de persona spécifiques au provider sous\n    `personas.<id>.providers.<provider>`. Les champs de prompt de persona sont ignorés\n    sauf si le provider implémente sa propre cartographie de persona-prompt.\n  </Accordion>\n</AccordionGroup>\n\n### Politique de repli\n\n`fallbackPolicy` contrôle le comportement lorsqu'un persona n'a **aucune liaison** pour le\nprovider tenté :\n\n| Politique           | Comportement                                                                                                                                                                       |\n| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `preserve-persona`  | **Par défaut.** Les champs de prompt neutres vis-à-vis du provider restent disponibles ; le provider peut les utiliser ou les ignorer.                                             |\n| `provider-defaults` | Le persona est omis de la préparation du prompt pour cette tentative ; le provider utilise ses paramètres neutres par défaut tandis que le repli vers d'autres providers continue. |\n| `fail`              | Ignore cette tentative de provider avec `reasonCode: \"not_configured\"` et `personaBinding: \"missing\"`. Les providers de repli sont toujours essayés.                               |\n\nL'ensemble de la demande TTS échoue uniquement lorsque **tous** les providers tentés sont ignorés\nou échouent.\n\nLa sélection de provider de session Talk est limitée à la session. Un client Talk doit choisir\nles ids de provider, les ids de modèle, les ids de voix et les paramètres régionaux à partir de `talk.catalog` et les transmettre\nvia la session Talk ou la demande de transfert. L'ouverture d'une session vocale ne doit\npas modifier `messages.tts` ni les paramètres par défaut globaux des providers Talk.\n\n## Directives basées sur le modèle\n\nPar défaut, l'assistant **peut** émettre des directives `[[tts:...]]` pour remplacer\nla voix, le modèle ou la vitesse pour une seule réponse, plus un bloc\n`[[tts:text]]...[[/tts:text]]` optionnel pour les indices expressifs qui doivent apparaître dans\nl'audio uniquement :\n\n```text\nHere you go.\n\n[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]\n[[tts:text]](laughs) Read the song once more.[[/tts:text]]\n```\n\nLorsque `messages.tts.auto` est `\"tagged\"`, les **directives sont requises** pour déclencher\nl'audio. La livraison de blocs en continu supprime les directives du texte visible avant que\nle channel ne les voie, même lorsqu'elles sont réparties sur des blocs adjacents.\n\n`provider=...` est ignoré sauf si `modelOverrides.allowProvider: true`. Lorsqu'une réponse déclare `provider=...`, les autres clés de cette directive sont analysées uniquement par ce provider ; les clés non prises en charge sont supprimées et signalées en tant qu'avertissements de directive TTS.\n\n**Clés de directive disponibles :**\n\n- `provider` (id de provider enregistré ; nécessite `allowProvider: true`)\n- `speakerVoice` / `speakerVoiceId` (anciens alias : `voice`, `voiceName`, `voice_name`, `google_voice`, `voiceId`)\n- `model` / `google_model`\n- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`\n- `vol` / `volume` (volume MiniMax, 0–10)\n- `pitch` (hauteur entière MiniMax, −12 à 12 ; les valeurs fractionnaires sont tronquées)\n- `emotion` (balise d'émotion Volcengine)\n- `applyTextNormalization` (`auto|on|off`)\n- `languageCode` (ISO 639-1)\n- `seed`\n\n**Désactiver entièrement les substitutions par le modèle :**\n\n```json5\n{ messages: { tts: { modelOverrides: { enabled: false } } } }\n```\n\n**Autoriser le changement de provider tout en gardant les autres paramètres configurables :**\n\n```json5\n{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }\n```\n\n## Commandes slash\n\nCommande unique `/tts`. Sur Discord, OpenClaw enregistre également `/voice` car `/tts` est une commande intégrée à Discord — le texte `/tts ...` fonctionne toujours.\n\n```text\n/tts off | on | status\n/tts chat on | off | default\n/tts latest\n/tts provider <id>\n/tts persona <id> | off\n/tts limit <chars>\n/tts summary off\n/tts audio <text>\n```\n\n<Note>Les commandes nécessitent un expéditeur autorisé (les règles de liste blanche/propriétaire s'appliquent) et `commands.text` ou l'enregistrement de commandes natif doit être activé.</Note>\n\nNotes sur le comportement :\n\n- `/tts on` écrit la préférence TTS locale dans `always` ; `/tts off` l'écrit dans `off`.\n- `/tts chat on|off|default` écrit une substitution auto-TTS limitée à la session pour la discussion actuelle.\n- `/tts persona <id>` écrit la préférence de personnalité locale ; `/tts persona off` l'efface.\n- `/tts latest` lit la dernière réponse de l'assistant à partir de la transcription de la session actuelle et l'envoie sous forme audio une seule fois. Il stocke uniquement un hachage de cette réponse dans l'entrée de session pour éviter les envois vocaux en double.\n- `/tts audio` génère une réponse audio ponctuelle (n'**active pas** le TTS).\n- `limit` et `summary` sont stockés dans les **préférences locales**, et non dans la configuration principale.\n- `/tts status` inclut des diagnostics de repli pour la dernière tentative — `Fallback: <primary> -> <used>`, `Attempts: ...`, et les détails de chaque tentative (`provider:outcome(reasonCode) latency`).\n- `/status` affiche le mode TTS actif ainsi que le provider, le modèle, la voix et les métadonnées du point de terminaison personnalisé nettoyés lorsque le TTS est activé.\n\n## Préférences par utilisateur\n\nLes commandes slash écrivent des substitutions locales dans `prefsPath`. La valeur par défaut est\n`~/.openclaw/settings/tts.json` ; remplacez-la avec la variable d'environnement `OPENCLAW_TTS_PREFS`\nou `messages.tts.prefsPath`.\n\n| Champ stocké | Effet                                             |\n| ------------ | ------------------------------------------------- |\n| `auto`       | Substitution locale auto-TTS (`always`, `off`, …) |\n| `provider`   | Substitution locale du provider principal         |\n| `persona`    | Substitution locale de personnalité               |\n| `maxLength`  | Seuil de résumé (par défaut `1500` caractères)    |\n| `summarize`  | Commutateur de résumé (par défaut `true`)         |\n\nCes éléments remplacent la configuration effective de `messages.tts` ainsi que le bloc\n`agents.list[].tts` actif pour cet hôte.\n\n## Formats de sortie (fixes)\n\nLa diffusion vocale TTS est pilotée par les capacités du canal. Les plugins de canal indiquent\nsi le TTS de type vocal doit demander aux providers une cible native `voice-note` ou\nconserver une synthèse `audio-file` normale et marquer uniquement la sortie compatible pour la diffusion\nvocale.\n\n- **Canaux compatibles avec les notes vocales** : les réponses par note vocale préfèrent Opus (`opus_48000_64` d'ElevenLabs, `opus`OpenAI d'OpenAI).\n  - 48 kHz / 64 kbps est un bon compromis pour les messages vocaux.\n- **Feishu / WhatsApp** : lorsqu'une réponse par note vocale est produite en MP3/WebM/WAV/M4A ou dans un autre format de fichier audio probable, le plugin de canal le transcode en Ogg/Opus 48 kHz avec WhatsApp`ffmpeg`WhatsAppBaileys avant d'envoyer le message vocal natif. WhatsApp envoie le résultat via la charge utile `audio` de Baileys avec `ptt: true` et `audio/ogg; codecs=opus`WhatsApp. Si la conversion échoue, Feishu reçoit le fichier d'origine en pièce jointe ; l'envoi WhatsApp échoue plutôt que de poster une charge utile PTT incompatible.\n- **Autres canaux** : MP3 (`mp3_44100_128` d'ElevenLabs, `mp3`OpenAI d'OpenAI).\n  - 44,1 kHz / 128 kbps est l'équilibre par défaut pour la clarté de la parole.\n- **MiniMax** : MP3 (modèle MiniMax`speech-2.8-hd`OpenClawMiniMax, taux d'échantillonnage 32 kHz) pour les pièces jointes audio normales. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode le MP3 de MiniMax en Opus 48 kHz avec `ffmpeg` avant la livraison lorsque le canal annonce la prise en charge du transcodage.\n- **Xiaomi MiMo** : MP3 par défaut, ou WAV si configuré. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode la sortie Xiaomi en Opus 48 kHz avec XiaomiOpenClawXiaomi`ffmpeg` avant la livraison lorsque le canal annonce la prise en charge du transcodage.\n- **CLI locale** : utilise le CLI`outputFormat` configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonique est convertie en PCM mono brut 16 kHz avec `ffmpeg`.\n- **Google Gemini** : l'API TTS Gemini renvoie du PCM brut 24 kHz. OpenClaw l'enveloppe en WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie le PCM directement pour Talk/téléphonie.\n- **Gradium** : WAV pour les pièces jointes audio, Opus pour les cibles de notes vocales, et `ulaw_8000` à 8 kHz pour la téléphonie.\n- **Inworld** : MP3 pour les pièces jointes audio normales, `OGG_OPUS` natif pour les cibles de notes vocales, et `PCM` brut à 22050 Hz pour Talk/téléphonie.\n- **xAI** : MP3 par défaut ; `responseFormat` peut être `mp3`, `wav`, `pcm`, `mulaw`, ou `alaw`OpenClaw. OpenClaw utilise le point de terminaison REST TTS par lot d'xAI et renvoie une pièce jointe audio complète ; le WebSocket TTS en flux d'xAI n'est pas utilisé par ce chemin de fournisseur. Le format de note vocale Opus natif n'est pas pris en charge par ce chemin.\n- **Microsoft** : utilise `microsoft.outputFormat` (par défaut `audio-24khz-48kbitrate-mono-mp3`).\n  - Le transport groupé accepte un `outputFormat`, mais tous les formats ne sont pas disponibles auprès du service.\n  - Les valeurs de format de sortie suivent les formats de sortie de Microsoft Speech (y compris Ogg/WebM Opus).\n  - Telegram Telegram`sendVoice`OpenAI accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis.\n  - Si le format de sortie Microsoft configuré échoue, OpenClaw réessaie avec MP3.\n\nLes formats de sortie OpenAI/ElevenLabs sont fixes par canal (voir ci-dessus).\n\n## Comportement TTS automatique\n\nLorsque `messages.tts.auto`OpenClaw est activé, OpenClaw :\n\n- Ignore le TTS si la réponse contient déjà des médias structurés.\n- Ignore les réponses très courtes (moins de 10 caractères).\n- Résume les longues réponses lorsque les résumés sont activés, en utilisant `summaryModel` (ou `agents.defaults.model.primary`).\n- Joint l'audio généré à la réponse.\n- En mode `mode: \"final\"`, envoie toujours du TTS audio uniquement pour les réponses finales en flux après la fin du flux de texte ; les médias générés passent par la même normalisation des médias de canal que les pièces jointes de réponses normales.\n\nSi la réponse dépasse `maxLength`API et que le résumé est désactivé (ou qu'il n'y a pas de clé API pour le modèle de résumé), l'audio est ignoré et la réponse texte normale est envoyée.\n\n```text\nReply -> TTS enabled?\n  no  -> send text\n  yes -> has media / short?\n          yes -> send text\n          no  -> length > limit?\n                   no  -> TTS -> attach audio\n                   yes -> summary enabled?\n                            no  -> send text\n                            yes -> summarize -> TTS -> attach audio\n```\n\n## Formats de sortie par canal\n\n| Cible                                 | Format                                                                                                                                                       |\n| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Feishu / Matrix / Telegram / WhatsApp | Les réponses en note vocale préfèrent **Opus** (`opus_48000_64` d'ElevenLabs, `opus` de OpenAI). 48 kHz / 64 kbps offre un équilibre entre clarté et taille. |\n| Autres canaux                         | **MP3** (`mp3_44100_128` d'ElevenLabs, `mp3` de OpenAI). 44,1 kHz / 128 kbps par défaut pour la voix.                                                        |\n| Talk / téléphonie                     | **PCM** natif du fournisseur (Inworld 22050 Hz, Google 24 kHz), ou `ulaw_8000` de Gradium pour la téléphonie.                                                |\n\nNotes par fournisseur :\n\n- **Transcodage Feishu / WhatsApp :** Lorsqu'une réponse en note vocale est au format MP3/WebM/WAV/M4A, le plugin de canal la transcode en Ogg/Opus 48 kHz avec `ffmpeg`. WhatsApp envoie via Baileys avec `ptt: true` et `audio/ogg; codecs=opus`. Si la conversion échoue : Feishu revient à l'attachement du fichier original ; l'envoi WhatsApp échoue plutôt que de poster une charge PTT incompatible.\n- **MiniMaxXiaomi / Xiaomi MiMo :** MP3 par défaut (32 kHz pour MiniMax `speech-2.8-hd`) ; transcodé en Opus 48 kHz pour les cibles de notes vocales via `ffmpeg`.\n- **CLI local :** Utilise le `outputFormat` configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonique en PCM mono brut 16 kHz.\n- **Google Gemini :** Renvoie du PCM brut 24 kHz. OpenClaw l'enveloppe en WAV pour les pièces jointes, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie le PCM directement pour Talk/téléphonie.\n- **Inworld :** Pièces jointes MP3, note vocale native `OGG_OPUS`, `PCM` brut 22050 Hz pour Talk/téléphonie.\n- **xAI :** MP3 par défaut ; `responseFormat` peut être `mp3|wav|pcm|mulaw|alaw`. Utilise le point de terminaison REST par lot de xAI — la TTS WebSocket en continu n'est **pas** utilisée. Le format de note vocale Opus natif n'est **pas** pris en charge.\n- **Microsoft :** Utilise `microsoft.outputFormat` (par défaut `audio-24khz-48kbitrate-mono-mp3`). Telegram `sendVoice` accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis. Si le format Microsoft configuré échoue, OpenClaw réessaie avec MP3.\n\nLes formats de sortie de OpenAI et ElevenLabs sont fixes par channel, comme indiqué ci-dessus.\n\n## Référence des champs\n\n<AccordionGroup>\n  <Accordion title=\"Top-level messages.tts.*\">\n    <ParamField path=\"auto\" type='\"off\" | \"always\" | \"inbound\" | \"tagged\"'>\n      Mode TTS automatique. `inbound` envoie l'audio uniquement après un message vocal entrant ; `tagged` n'envoie l'audio que si la réponse inclut des directives `[[tts:...]]` ou un bloc `[[tts:text]]`.\n    </ParamField>\n    <ParamField path=\"enabled\" type=\"boolean\" deprecated>\n      Commutateur hérité. `openclaw doctor --fix` migre ceci vers `auto`.\n    </ParamField>\n    <ParamField path=\"mode\" type='\"final\" | \"all\"' default=\"final\">\n      `\"all\"` inclut les réponses d'outils/blocs en plus des réponses finales.\n    </ParamField>\n    <ParamField path=\"provider\" type=\"string\">\n      Identifiant du fournisseur de synthèse vocale. Si non défini, OpenClaw utilise le premier fournisseur configuré dans l'ordre de sélection automatique du registre. L'ancien `provider: \"edge\"` est réécrit en `\"microsoft\"` par `openclaw doctor --fix`.\n    </ParamField>\n    <ParamField path=\"persona\" type=\"string\">\n      Identifiant de persona actif depuis `personas`. Normalisé en minuscules.\n    </ParamField>\n    <ParamField path=\"personas.<id>\" type=\"object\">\n      Identité vocale stable. Champs : `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.<provider>`. Voir [Personas](#personas).\n    </ParamField>\n    <ParamField path=\"summaryModel\" type=\"string\">\n      Modèle économique pour le résumé automatique ; par défaut `agents.defaults.model.primary`. Accepte `provider/model` ou un alias de modèle configuré.\n    </ParamField>\n    <ParamField path=\"modelOverrides\" type=\"object\">\n      Autoriser le modèle à émettre des directives TTS. `enabled` par défaut est `true` ; `allowProvider` par défaut est `false`.\n    </ParamField>\n    <ParamField path=\"providers.<id>\" type=\"object\">\n      Paramètres appartenant au fournisseur, indexés par l'identifiant du fournisseur de synthèse vocale. Les blocs directs hérités (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) sont réécrits par `openclaw doctor --fix` ; ne commitez que `messages.tts.providers.<id>`.\n    </ParamField>\n    <ParamField path=\"maxTextLength\" type=\"number\">\n      Limite stricte pour les caractères d'entrée TTS. `/tts audio` échoue si dépassé.\n    </ParamField>\n    <ParamField path=\"timeoutMs\" type=\"number\">\n      Délai d'expiration de la requête en millisecondes.\n    </ParamField>\n    <ParamField path=\"prefsPath\" type=\"string\">\n      Remplacer le chemin JSON des préférences locales (provider/limit/summary). Par défaut `~/.openclaw/settings/tts.json`.\n    </ParamField>\n  </Accordion>\n\n<Accordion title=\"Azure Speech\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env : `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` ou `SPEECH_KEY`.\n  </ParamField>\n  <ParamField path=\"region\" type=\"string\">\n    Région Azure Speech (p. ex. `eastus`). Env : `AZURE_SPEECH_REGION` ou `SPEECH_REGION`.\n  </ParamField>\n  <ParamField path=\"endpoint\" type=\"string\">\n    Remplacement facultatif du point de terminaison Azure Speech (alias `baseUrl`).\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    ShortName de la voix Azure. Par défaut `en-US-JennyNeural`. Alias de l'ancienne version : `voice`.\n  </ParamField>\n  <ParamField path=\"lang\" type=\"string\">\n    Code de langue SSML. Par défaut `en-US`.\n  </ParamField>\n  <ParamField path=\"outputFormat\" type=\"string\">\n    Azure `X-Microsoft-OutputFormat` pour l'audio standard. Par défaut `audio-24khz-48kbitrate-mono-mp3`.\n  </ParamField>\n  <ParamField path=\"voiceNoteOutputFormat\" type=\"string\">\n    Azure `X-Microsoft-OutputFormat` pour la sortie en note vocale. Par défaut `ogg-24khz-16bit-mono-opus`.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"ElevenLabs\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Revient à `ELEVENLABS_API_KEY` ou `XI_API_KEY`.\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    ID du modèle (ex. `eleven_multilingual_v2`, `eleven_v3`).\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    ID de la voix ElevenLabs. Alias hérité : `voiceId`.\n  </ParamField>\n  <ParamField path=\"voiceSettings\" type=\"object\">\n    `stability`, `similarityBoost`, `style` (chacun `0..1`), `useSpeakerBoost` (`true|false`), `speed` (`0.5..2.0`, `1.0` = normal).\n  </ParamField>\n  <ParamField path=\"applyTextNormalization\" type='\"auto\" | \"on\" | \"off\"'>\n    Mode de normalisation du texte.\n  </ParamField>\n  <ParamField path=\"languageCode\" type=\"string\">\n    ISO 639-1 sur 2 lettres (ex. `en`, `de`).\n  </ParamField>\n  <ParamField path=\"seed\" type=\"number\">\n    Entier `0..4294967295` pour un déterminisme au mieux.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Remplacer l'URL de base de l'API ElevenLabs.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Google Gemini\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Revient à `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Si omis, le TTS peut réutiliser `models.providers.google.apiKey` avant le repli vers l'environnement.\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    Modèle TTS Gemini. Par défaut `gemini-3.1-flash-tts-preview`.\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Nom de la voix prédéfinie Gemini. Par défaut `Kore`. Alias historiques : `voiceName`, `voice`.\n  </ParamField>\n  <ParamField path=\"audioProfile\" type=\"string\">\n    Invite de style en langage naturel ajoutée avant le texte parlé.\n  </ParamField>\n  <ParamField path=\"speakerName\" type=\"string\">\n    Étiquette de locuteur optionnelle ajoutée avant le texte parlé lorsque votre invite utilise un locuteur nommé.\n  </ParamField>\n  <ParamField path=\"promptTemplate\" type='\"audio-profile-v1\"'>\n    Définir sur `audio-profile-v1` pour encapsuler les champs d'invite de persona actifs dans une structure d'invite TTS Gemini déterministe.\n  </ParamField>\n  <ParamField path=\"personaPrompt\" type=\"string\">\n    Texte d'invite de persona supplémentaire spécifique à Google, ajouté aux Notes du réalisateur du modèle.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Seul `https://generativelanguage.googleapis.com` est accepté.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Gradium\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env : `GRADIUM_API_KEY`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Par défaut `https://api.gradium.ai`.\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    Emma par défaut (`YTpq7expH9539ERJ`). Alias historique : `voiceId`.\n  </ParamField>\n</Accordion>\n\n  <Accordion title=\"Inworld\">\n    ### Inworld principal\n\n    <ParamField path=\"apiKey\" type=\"string\">Env : `INWORLD_API_KEY`.</ParamField>\n    <ParamField path=\"baseUrl\" type=\"string\">Par défaut `https://api.inworld.ai`.</ParamField>\n    <ParamField path=\"modelId\" type=\"string\">Par défaut `inworld-tts-1.5-max`. Aussi : `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`.</ParamField>\n    <ParamField path=\"speakerVoiceId\" type=\"string\">Par défaut `Sarah`. Alias hérité : `voiceId`.</ParamField>\n    <ParamField path=\"temperature\" type=\"number\">Température d'échantillonnage `0..2`.</ParamField>\n\n  </Accordion>\n\n<Accordion title=\"CLI local (tts-local-cli)\">\n  <ParamField path=\"command\" type=\"string\">\n    Exécutable local ou chaîne de commande pour le TTS CLI.\n  </ParamField>\n  <ParamField path=\"args\" type=\"string[]\">\n    Arguments de commande. Prend en charge les espaces réservés `{{ Text }}`, `{{ OutputPath }}`, `{{ OutputDir }}`, `{{ OutputBase }}`.\n  </ParamField>\n  <ParamField path=\"outputFormat\" type='\"mp3\" | \"opus\" | \"wav\"'>\n    Format de sortie CLI attendu. Par défaut `mp3` pour les pièces jointes audio.\n  </ParamField>\n  <ParamField path=\"timeoutMs\" type=\"number\">\n    Délai d'attente de la commande en millisecondes. Par défaut `120000`.\n  </ParamField>\n  <ParamField path=\"cwd\" type=\"string\">\n    Répertoire de travail optionnel pour la commande.\n  </ParamField>\n  <ParamField path=\"env\" type=\"Record<string, string>\">\n    Remplacements d'environnement optionnels pour la commande.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"APIMicrosoft (sans clé API)\">\n  <ParamField path=\"enabled\" type=\"boolean\" default=\"true\">\n    Autoriser l'utilisation de la synthèse vocale Microsoft.\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Nom de la voix neurale Microsoft (ex. `en-US-MichelleNeural`). Alias hérité : `voice`.\n  </ParamField>\n  <ParamField path=\"lang\" type=\"string\">\n    Code de langue (ex. `en-US`).\n  </ParamField>\n  <ParamField path=\"outputFormat\" type=\"string\">\n    Format de sortie Microsoft. Par défaut `audio-24khz-48kbitrate-mono-mp3`. Tous les formats ne sont pas pris en charge par le transport Edge inclus.\n  </ParamField>\n  <ParamField path=\"rate / pitch / volume\" type=\"string\">\n    Chaînes de pourcentage (ex. `+10%`, `-5%`).\n  </ParamField>\n  <ParamField path=\"saveSubtitles\" type=\"boolean\">\n    Écrire des sous-titres JSON avec le fichier audio.\n  </ParamField>\n  <ParamField path=\"proxy\" type=\"string\">\n    URL du proxy pour les requêtes de synthèse vocale Microsoft.\n  </ParamField>\n  <ParamField path=\"timeoutMs\" type=\"number\">\n    Remplacement du délai d'expiration de la requête (ms).\n  </ParamField>\n  <ParamField path=\"edge.*\" type=\"object\" deprecated>\n    Alias hérité. Exécutez `openclaw doctor --fix` pour réécrire la configuration persistante vers `providers.microsoft`.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"MiniMaxMiniMax\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Retourne à `MINIMAX_API_KEY`. Auth Token Plan via `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, ou `MINIMAX_CODING_API_KEY`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Par défaut `https://api.minimax.io`. Env : `MINIMAX_API_HOST`.\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    Par défaut `speech-2.8-hd`. Env : `MINIMAX_TTS_MODEL`.\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    Par défaut `English_expressive_narrator`. Env : `MINIMAX_TTS_VOICE_ID`. Alias historique : `voiceId`.\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    `0.5..2.0`. Par défaut `1.0`.\n  </ParamField>\n  <ParamField path=\"vol\" type=\"number\">\n    `(0, 10]`. Par défaut `1.0`.\n  </ParamField>\n  <ParamField path=\"pitch\" type=\"number\">\n    Entier `-12..12`. Par défaut `0`. Les valeurs fractionnaires sont tronquées avant la requête.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"OpenAIOpenAI\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Revient à `OPENAI_API_KEY`.\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\" OpenAI>\n    ID du model TTS OpenAI (par ex. `gpt-4o-mini-tts`).\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Nom de la voix (par ex. `alloy`, `cedar`). Alias hérité : `voice`.\n  </ParamField>\n  <ParamField path=\"instructions\" type=\"string\" OpenAI>\n    Champ `instructions` OpenAI explicite. Lorsqu'il est défini, les champs de prompt de persona ne sont **pas** mappés automatiquement.\n  </ParamField>\n  <ParamField path=\"extraBody / extra_body\" type=\"Record<string, unknown>\">\n    Champs JSON supplémentaires fusionnés dans les corps de requête `/audio/speech`OpenAIOpenAI après les champs TTS OpenAI générés. À utiliser pour les points de terminaison compatibles OpenAI tels que Kokoro qui nécessitent des clés spécifiques au provider comme `lang` ; les clés de prototype non sécurisées sont ignorées.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\" OpenAI>\n    Remplacer le point de terminaison TTS OpenAI. Ordre de résolution : config → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`OpenAI. Les valeurs par défaut sont traitées comme des points de terminaison TTS compatibles OpenAI, donc les noms de model et de voix personnalisés sont acceptés.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"OpenRouterOpenRouter\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env : `OPENROUTER_API_KEY`. Peut réutiliser `models.providers.openrouter.apiKey`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Par défaut `https://openrouter.ai/api/v1`. L'ancien `https://openrouter.ai/v1` est normalisé.\n  </ParamField>\n  <ParamField path=\"model\" type=\"string\">\n    Par défaut `hexgrad/kokoro-82m`. Alias : `modelId`.\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Par défaut `af_alloy`. Anciens alias : `voice`, `voiceId`.\n  </ParamField>\n  <ParamField path=\"responseFormat\" type='\"mp3\" | \"pcm\"'>\n    Par défaut `mp3`.\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    Surcharge de vitesse propre au fournisseur.\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"Volcengine (BytePlus Seed Speech)\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env : `VOLCENGINE_TTS_API_KEY` ou `BYTEPLUS_SEED_SPEECH_API_KEY`.\n  </ParamField>\n  <ParamField path=\"resourceId\" type=\"string\">\n    Par défaut `seed-tts-1.0`. Env : `VOLCENGINE_TTS_RESOURCE_ID`. Utilisez `seed-tts-2.0` lorsque votre projet dispose de droits TTS 2.0.\n  </ParamField>\n  <ParamField path=\"appKey\" type=\"string\">\n    En-tête de clé d'application. Par défaut `aGjiRDfUWi`. Env : `VOLCENGINE_TTS_APP_KEY`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Remplacer le point de terminaison HTTP TTS Seed Speech. Env : `VOLCENGINE_TTS_BASE_URL`.\n  </ParamField>\n  <ParamField path=\"speakerVoice\" type=\"string\">\n    Type de voix. Par défaut `en_female_anna_mars_bigtts`. Env : `VOLCENGINE_TTS_VOICE`. Alias hérité : `voice`.\n  </ParamField>\n  <ParamField path=\"speedRatio\" type=\"number\">\n    Rapport de vitesse natif du fournisseur.\n  </ParamField>\n  <ParamField path=\"emotion\" type=\"string\">\n    Balise d'émotion native du fournisseur.\n  </ParamField>\n  <ParamField path=\"appId / token / cluster\" type=\"string\" deprecated>\n    Champs hérités de la console vocale Volcengine. Env : `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (par défaut `volcano_tts`).\n  </ParamField>\n</Accordion>\n\n<Accordion title=\"xAI\">\n  <ParamField path=\"apiKey\" type=\"string\">\n    Env : `XAI_API_KEY`.\n  </ParamField>\n  <ParamField path=\"baseUrl\" type=\"string\">\n    Par défaut `https://api.x.ai/v1`. Env : `XAI_BASE_URL`.\n  </ParamField>\n  <ParamField path=\"speakerVoiceId\" type=\"string\">\n    Par défaut `eve`. Voix en direct : `ara`, `eve`, `leo`, `rex`, `sal`, `una`. Alias hérité : `voiceId`.\n  </ParamField>\n  <ParamField path=\"language\" type=\"string\">\n    Code de langue BCP-47 ou `auto`. Par défaut `en`.\n  </ParamField>\n  <ParamField path=\"responseFormat\" type='\"mp3\" | \"wav\" | \"pcm\" | \"mulaw\" | \"alaw\"'>\n    Par défaut `mp3`.\n  </ParamField>\n  <ParamField path=\"speed\" type=\"number\">\n    Remplacement de la vitesse natif du fournisseur.\n  </ParamField>\n</Accordion>\n\n  <Accordion title=\"Xiaomi MiMo\">\n    <ParamField path=\"apiKey\" type=\"string\">Env : `XIAOMI_API_KEY`.</ParamField>\n    <ParamField path=\"baseUrl\" type=\"string\">Par défaut `https://api.xiaomimimo.com/v1`. Env : `XIAOMI_BASE_URL`.</ParamField>\n    <ParamField path=\"model\" type=\"string\">Par défaut `mimo-v2.5-tts`. Env : `XIAOMI_TTS_MODEL`. Prend également en charge `mimo-v2-tts` et `mimo-v2.5-tts-voicedesign`.</ParamField>\n    <ParamField path=\"speakerVoice\" type=\"string\">Par défaut `mimo_default` pour les modèles de voix prédéfinis. Env : `XIAOMI_TTS_VOICE`. Alias hérité : `voice`. Non envoyé pour `mimo-v2.5-tts-voicedesign`.</ParamField>\n    <ParamField path=\"format\" type='\"mp3\" | \"wav\"'>Par défaut `mp3`. Env : `XIAOMI_TTS_FORMAT`.</ParamField>\n    <ParamField path=\"style\" type=\"string\">Instruction de style en langage naturel facultative envoyée en tant que message utilisateur ; non prononcée. Pour `mimo-v2.5-tts-voicedesign`, il s'agit du prompt de conception vocale ; OpenClaw fournit une valeur par défaut en cas d'omission.</ParamField>\n  </Accordion>\n</AccordionGroup>\n\n## Agent tool\n\nL'outil `tts` convertit le texte en parole et renvoie une pièce jointe audio pour la livraison de la réponse. Sur Feishu, Matrix, Telegram et WhatsApp, l'audio est délivré sous forme de message vocal plutôt que de fichier pièce jointe. Feishu et WhatsApp peuvent transcoder la sortie TTS non Opus sur ce chemin lorsque `ffmpeg` est disponible.\n\nWhatsApp envoie l'audio via Baileys sous forme de note vocale PTT (`audio` avec `ptt: true`) et envoie le texte visible **séparément** de l'audio PTT car les clients ne rendent pas systématiquement les légendes sur les notes vocales.\n\nL'outil accepte les champs facultatifs `channel` et `timeoutMs` ; `timeoutMs` est un\ndélai d'expiration de la demande du provider par appel en millisecondes. Les valeurs par appel remplacent\n`messages.tts.timeoutMs` ; les délais d'expiration TTS configurés remplacent toute valeur par défaut du provider définie par le plugin.\n\n## Gateway RPC\n\n| Méthode           | Objet                                                  |\n| ----------------- | ------------------------------------------------------ |\n| `tts.status`      | Lire l'état actuel du TTS et la dernière tentative.    |\n| `tts.enable`      | Définir la préférence automatique locale sur `always`. |\n| `tts.disable`     | Définir la préférence automatique locale sur `off`.    |\n| `tts.convert`     | Conversion ponctuelle texte → audio.                   |\n| `tts.setProvider` | Définir la préférence locale du provider.              |\n| `tts.setPersona`  | Définir la préférence locale de personnalité.          |\n| `tts.providers`   | Lister les providers configurés et leur statut.        |\n\n## Liens de service\n\n- [OpenAI guide de synthèse vocale](https://platform.openai.com/docs/guides/text-to-speech)\n- [OpenAI Audio API référence](https://platform.openai.com/docs/api-reference/audio)\n- [Azure Speech REST synthèse vocale](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)\n- [Provider Azure Speech](/fr/providers/azure-speech)\n- [ElevenLabs Synthèse vocale](https://elevenlabs.io/docs/api-reference/text-to-speech)\n- [Authentification ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)\n- [Gradium](/fr/providers/gradium)\n- [Inworld TTS API](https://docs.inworld.ai/tts/tts)\n- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)\n- [Volcengine TTS HTTP API](/fr/providers/volcengine#text-to-speech)\n- [Xiaomi MiMo synthèse vocale](/fr/providers/xiaomi#text-to-speech)\n- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)\n- [Formats de sortie vocale Microsoft](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)\n- [xAI synthèse vocale](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)\n\n## Connexes\n\n- [Aperçu des médias](/fr/tools/media-overview)\n- [Génération musicale](/fr/tools/music-generation)\n- [Génération vidéo](/fr/tools/video-generation)\n- [Commandes de barre oblique](/fr/tools/slash-commands)\n- [Plugin d'appel vocal](/fr/plugins/voice-call)\n"}}}}