文本转语音命令和指令

模型驱动指令¶

默认情况下，助手可以输出 [[tts:...]] 指令，以覆盖单次回复的语音、模型或速度，还可以附带一个可选的 [[tts:text]]...[[/tts:text]] 块，用于仅应在音频中出现的表达性提示：

Here you go.

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

当 tts.auto 为 "tagged" 时，必须使用指令才能触发音频。流式块投递会在频道看到这些指令之前，从可见文本中剥离它们，即使指令被拆分到相邻的多个块中，也是如此。

provider=... 只有在 modelOverrides.allowProvider: true 时才会被采用。当回复声明了 provider=... 时，该指令中的其他键仅由该 provider 解析；不支持的键会被剥离并报告为 TTS 指令警告。

可用的指令键：

• provider（已注册的 provider id；需要 allowProvider: true）
• speakerVoice / speakerVoiceId（旧别名：voice、voiceName、voice_name、google_voice、voiceId）
• model / google_model
• stability、similarityBoost、style、speed、useSpeakerBoost
• vol / volume（MiniMax 音量，(0, 10]）
• pitch（MiniMax 整数音高，−12 到 12；小数会被截断）
• emotion（Volcengine 情感标签）
• applyTextNormalization（auto|on|off）
• languageCode（ISO 639-1）
• seed

完全禁用模型覆盖：

{ tts: { modelOverrides: { enabled: false } } }

允许切换 provider，同时保持其他旋钮可配置：

{ tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } }

斜杠命令¶

单条命令 /tts。在 Discord 上，OpenClaw 还会注册 /voice，因为 /tts 是 Discord 内置命令——文本形式的 /tts ... 仍然有效。

/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>

行为说明：

• /tts on 将本地 TTS 偏好写入 always；/tts off 将其写入 off。
• /tts chat on|off|default 为当前聊天写入一个会话作用域的自动 TTS 覆盖。
• /tts persona <id> 写入本地 persona 偏好；/tts persona off 清除它。
• /tts latest 从当前会话记录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目中存储该回复的哈希值，以抑制重复的语音发送。
• /tts audio 生成一次性的音频回复（不会打开 TTS）。
• /tts limit <chars> 接受 100–4096（4096 是 Telegram 的说明/消息最大长度）；超出该范围的值会被拒绝。
• limit 和 summary 存储在本地偏好中，而不是主配置中。
• /tts status 包含最近一次尝试的回退诊断信息——Fallback: <primary> -> <used>、Attempts: ...，以及每次尝试的详细信息（provider:outcome(reasonCode) latency）。
• /status 在 TTS 启用时，显示当前 TTS 模式以及已配置的 provider、模型、语音和经过净化的自定义端点元数据。

每用户偏好¶

斜杠命令会将本地覆盖写入 TTS 偏好路径。默认路径是 ~/.openclaw/settings/tts.json；可以使用 OPENCLAW_TTS_PREFS 覆盖它。Doctor 会将已废弃的全局 tts.prefsPath 值迁移到共享机器状态中。进阶的多代理设置中，如果各代理有意使用独立的偏好存储，仍然可以设置 agents.entries.<id>.tts.prefsPath。

这些字段会覆盖来自 tts 的有效配置，以及该主机上处于活动状态的 agents.entries.*.tts 块。