文本转语音命令和指令

模型驱动的指令

默认情况下，助手可以发出 [[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" 时，需要使用指令才能触发音频。流式块传递会在通道看到可见文本之前移除其中的指令，即使这些指令被拆分在相邻的多个块中。

回复可以完全由非空 [[tts:text]]...[[/tts:text]] 块组成。不需要可见的文本前缀，包括当模型也返回推理时。

除非 modelOverrides.allowProvider: true，否则 provider=... 将被忽略。当回复声明 provider=... 时，该指令中的其他键仅由该提供者解析；不支持的键将被删除并报告为 TTS 指令警告。

可用的指令键：

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

完全禁用模型覆盖：

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

允许切换提供商，同时保持其他参数可配置：

{ 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 caption/message 最大值）；超出该范围的值将被拒绝。
• limit 和 summary 存储在 本地偏好 中，而不是主配置中。
• /tts status 会包含最近一次尝试的回退诊断信息——Fallback: <primary> -> <used>、Attempts: ...，以及每次尝试的详细信息（provider:outcome(reasonCode) latency）。
• 当 TTS 启用时，/status 会显示当前 TTS 模式，以及已配置的 provider、model、voice 和已清理的自定义端点元数据。

每用户偏好

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

这些设置会覆盖该主机上来自 tts 以及当前激活的 agents.entries.*.tts 区块的有效配置。