功能工具
配置
TTS 配置位于 ~/.openclaw/openclaw.json 中的 tts 下。选择一个预设并调整提供程序块。下面显示的 speakerVoice/speakerVoiceId 字段是当前名称；每个提供商自己的 voice/voiceId/ voiceName 字段名称仍然用作旧别名。
OpenRouter 和 DeepInfra 在提供程序默认值之前按顺序使用 speakerVoice、speakerVoiceId、voice 和 voiceId 中的第一个非空值。 Talk 将相同的顺序应用于其提供程序块；当所有四个字段都不存在或空白时，它保留基本 TTS 语音。
Azure Speech
json5{ tts: { auto: "always", provider: "azure-speech", providers: { "azure-speech": { apiKey: "${AZURE_SPEECH_KEY}", region: "eastus", speakerVoice: "en-US-JennyNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus", }, }, },}
ElevenLabs
json5{ tts: { auto: "always", provider: "elevenlabs", providers: { elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", modelId: "eleven_multilingual_v2", speakerVoiceId: "EXAVITQu4vr4xnSDxMaL", }, }, },}
Fish Audio
json5{ tts: { auto: "tagged", provider: "fish-audio", providers: { "fish-audio": { apiKey: "${FISH_API_KEY}", model: "s2.1-pro", speakerVoiceId: "802e3bc2b27e49c2995d23ef70e6ac89", latency: "balanced", }, }, },}
Google Gemini
json5{ tts: { auto: "always", provider: "google", providers: { google: { apiKey: "${GEMINI_API_KEY}", model: "gemini-3.8-flash-tts", speakerVoice: "Kore", }, }, },}
Gradium
json5{ tts: { auto: "always", provider: "gradium", providers: { gradium: { apiKey: "${GRADIUM_API_KEY}", speakerVoiceId: "YTpq7expH9539ERJ", }, }, },}
Inworld
json5{ tts: { auto: "always", provider: "inworld", providers: { inworld: { apiKey: "${INWORLD_API_KEY}", modelId: "inworld-tts-1.5-max", speakerVoiceId: "Sarah", temperature: 0.7, }, }, },}
本地 CLI
json5{ tts: { auto: "always", provider: "tts-local-cli", providers: { "tts-local-cli": { command: "say", args: ["-o", "{{OutputPath}}", "{{Text}}"], outputFormat: "wav", timeoutMs: 120000, }, }, },}
Microsoft（无钥匙）
json5{ tts: { auto: "always", provider: "microsoft", providers: { microsoft: { enabled: true, speakerVoice: "en-US-MichelleNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", rate: "+0%", pitch: "+0%", }, }, },}
MiniMax
json5{ tts: { auto: "always", provider: "minimax", providers: { minimax: { apiKey: "${MINIMAX_API_KEY}", model: "speech-2.8-hd", speakerVoiceId: "English_expressive_narrator", speed: 1.0, vol: 1.0, pitch: 0, }, }, },}
OpenAI + ElevenLabs
json5{ tts: { auto: "always", provider: "openai", summaryModel: "openai/gpt-4.1-mini", modelOverrides: { enabled: true }, providers: { openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts", speakerVoice: "alloy", }, elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", modelId: "eleven_multilingual_v2", speakerVoiceId: "EXAVITQu4vr4xnSDxMaL", voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 }, applyTextNormalization: "auto", languageCode: "en", }, }, },}
OpenRouter
json5{ tts: { auto: "always", provider: "openrouter", providers: { openrouter: { apiKey: "${OPENROUTER_API_KEY}", model: "hexgrad/kokoro-82m", speakerVoice: "af_alloy", responseFormat: "mp3", }, }, },}
Volcengine
json5{ tts: { auto: "always", provider: "volcengine", providers: { volcengine: { apiKey: "${VOLCENGINE_TTS_API_KEY}", resourceId: "seed-tts-1.0", speakerVoice: "en_female_anna_mars_bigtts", }, }, },}
xAI
json5{ tts: { auto: "always", provider: "xai", providers: { xai: { apiKey: "${XAI_API_KEY}", speakerVoiceId: "eve", language: "en", responseFormat: "mp3", }, }, },}
Xiaomi MiMo
json5{ tts: { auto: "always", provider: "xiaomi", providers: { xiaomi: { apiKey: "${XIAOMI_API_KEY}", model: "mimo-v2.5-tts", speakerVoice: "mimo_default", format: "mp3", }, }, },}
对于 Xiaomi mimo-v2.5-tts-voicedesign，省略 speakerVoice 并将 style 设置为语音设计提示词。OpenClaw 会将该提示词作为 TTS 的 user 消息发送， 并且不会为 voicedesign 模型发送 audio.voice。
本地 Speech Swift 和 speech-core
Speech Swift 和 speech-core 提供跨 macOS、Linux 和 Windows 的本地语音推理。当 Speech Swift 和 OpenClaw 在同一台 Mac 上运行时，请使用 OpenAI- 兼容的 HTTP 提供程序。使用本地 CLI 在任何支持的主机上进行直接可执行集成。
当某个通道需要 OpenClaw 将 WAV 输出转换为 Opus 或原始 PCM 时，请安装 ffmpeg。
macOS HTTP
启动 Speech Swift 的本地服务器：
bashbrew install speechspeech-server --port 8080
将 OpenAI speech 提供程序指向其回环端点。responseFormat 必须是 wav，因为本地端点不会输出压缩音频：
json5{ tts: { auto: "always", provider: "openai", providers: { openai: { apiKey: "local", baseUrl: "http://127.0.0.1:8080/v1", model: "tts-1", speakerVoice: "alloy", responseFormat: "wav", }, }, },}
tts-1 会选择 Kokoro。Speech Swift 注册表别名，例如 qwen3-tts、 cosyvoice 和 voxcpm2 会选择其他本地引擎。占位用 API 密钥是 OpenClaw 提供程序配置所必需的，但不会被回环服务器验证。
macOS CLI
Homebrew 的 speech 可执行文件可以直接写入 OpenClaw 每次调用的输出路径：
json5{ tts: { auto: "always", provider: "tts-local-cli", providers: { "tts-local-cli": { command: "speech", args: ["speak", "{{Text}}", "--output", "{{OutputPath}}"], outputFormat: "wav", timeoutMs: 120000, }, }, },}
Linux CLI
安装 speech-core Linux 发布包，下载一次 ONNX 模型集，并在启动 OpenClaw 之前验证合成：
bashspeech download-modelsspeech speak "Hello from OpenClaw" hello.wav
然后配置打包的 Kokoro 命令：
json5{ tts: { auto: "always", provider: "tts-local-cli", providers: { "tts-local-cli": { command: "speech", args: ["speak", "{{Text}}", "{{OutputPath}}"], outputFormat: "wav", timeoutMs: 120000, }, }, },}
有关发布包和模型目录设置，请参阅 speech-core Linux CLI 参考 。
Windows CLI
下载 speech-core Windows 发布版，解压它，并安装一次 ONNX 模型：
powershell$Version = "0.0.11"$Url = "https://github.com/soniqo/speech-core/releases/download/v$Version/speech-$Version-windows-x64.zip"Invoke-WebRequest $Url -OutFile speech.zipExpand-Archive speech.zipSet-Location "speech\speech-$Version-windows-x64\bin"Set-ExecutionPolicy -Scope Process Bypass.\speech_download_models.ps1
Set-ExecutionPolicy -Scope Process Bypass 仅允许未签名的 speech_download_models.ps1 在此 shell 中运行。 -Scope Process 不改变机器或用户执行策略，当 shell 退出时放松结束。
然后将 Local CLI 指向打包的 Kokoro 可执行文件。将 C:\path\to 替换为您的提取目录，并将 0.0.11 替换为您下载的 $Version：
json5{ tts: { auto: "always", provider: "tts-local-cli", providers: { "tts-local-cli": { command: "C:\\path\\to\\speech-0.0.11-windows-x64\\bin\\speech_synthesize.exe", args: ["{{OutputPath}}", "{{Text}}", "en"], outputFormat: "wav", timeoutMs: 120000, }, }, },}
有关打包服务器、模型缓存和独立命令语法，请参阅 speech-core Windows CLI 参考 。
每个代理的语音覆盖
当某个代理应使用不同的提供商、声音、模型、角色设定或自动 TTS 模式时，使用 agents.entries.*.tts。代理块会对 tts 进行深度合并，因此提供商凭据可以保留在全局提供商配置中：
json5{ tts: { auto: "always", provider: "elevenlabs", providers: { elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", modelId: "eleven_multilingual_v2" }, }, }, agents: { entries: { reader: { tts: { providers: { elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" }, }, }, }, }, },}
要为某个代理固定角色设定，请将 agents.entries.*.tts.persona 与提供商配置一起设置——它只会覆盖该代理的全局 tts.persona。
自动回复、/tts audio、/tts status 和 tts 代理工具的优先顺序。后面的层获胜：每一层都深度合并其上面的层，因此设置字段的最后一层决定其值。
tts- 活跃的
agents.entries.*.tts
- 当该频道支持
channels.<channel>.tts 时的频道覆盖
- 当该频道传递
channels.<channel>.accounts.<id>.tts 时的账号覆盖
- 此主机的本地
/tts 首选项
- 启用 model overrides 时的 inline
[[tts:...]] 指令
频道和账号覆盖使用与 tts 相同的结构，并在更早的层之上进行深度合并，因此共享的提供商凭据可以保留在 tts 中，而频道或机器人账号只更改声音、模型、角色设定或自动模式：
json5{ tts: { provider: "openai", providers: { openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" }, }, }, channels: { feishu: { accounts: { english: { tts: { providers: { openai: { speakerVoice: "shimmer" }, }, }, }, }, }, },}
