在 OpenClaw 中使用 Gradium TTS 时，API Key 认证失败通常因环境变量或配置键未正确设置。语音覆盖不生效需检查 speech policy 是否允许；输出格式由目标表面自动选择，不可在 openclaw.json 中配置。验证：执行 openclaw doctor 确认 apiKey 已解析。

OpenClaw Gradium TTS 配置与语音覆盖问题排查

Gradium 是 OpenClaw 内置的文本转语音（TTS）提供商。该插件支持标准音频回复（WAV）、类语音笔记的 Opus 输出，以及用于电话等场景的 8 kHz u-law 音频。

属性	值
Provider id	gradium
认证方式	GRADIUM_API_KEY 环境变量 或 apiKey 配置
基础 URL	https://api.gradium.ai (默认)
默认语音	Emma (YTpq7expH9539ERJ)

怎么配置 Gradium TTS

创建 Gradium API Key 后，通过环境变量或配置键暴露给 OpenClaw。

环境变量

```bash
export GRADIUM_API_KEY="gsk_..."
```

配置文件

```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
        },
      },
    },
  },
}
```

插件会优先检查 apiKey 配置键，如果未设置，则回退到 GRADIUM_API_KEY 环境变量。

配置参数

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          voiceId: "YTpq7expH9539ERJ",
          // apiKey: "${GRADIUM_API_KEY}",
          // baseUrl: "https://api.gradium.ai",
        },
      },
    },
  },
}

Key	类型	说明
messages.tts.providers.gradium.apiKey	string	解析后的 API Key。支持 ${ENV} 和 secret ref 引用。
messages.tts.providers.gradium.baseUrl	string	覆盖 API 地址。尾部斜杠会被去除。默认值为 https://api.gradium.ai。
messages.tts.providers.gradium.voiceId	string	默认语音 ID，当没有指令覆盖时使用。

输出音频格式由运行时根据目标表面自动选择，不可在 openclaw.json 中配置。参见下方 输出格式 说明。

支持的语音

名称	Voice ID
Emma	YTpq7expH9539ERJ
Kent	LFZvm12tW_z0xfGo
Tiffany	Eu9iL_CYe8N-Gkx_
Christina	2H4HY2CBNyJHBCrP
Sydney	jtEKaLYNn6iif5PR
John	KWJiFWu2O9nMPYcR
Arthur	3jUdJyOi9pgbxBTK

默认语音：Emma。

每消息语音覆盖

当当前语音策略允许覆盖时，你可以在消息中使用指令标记来切换语音。以下所有标记都会解析为相同的 voiceId 覆盖：

/voice:LFZvm12tW_z0xfGo
/voice_id:LFZvm12tW_z0xfGo
/voiceid:LFZvm12tW_z0xfGo
/gradium_voice:LFZvm12tW_z0xfGo
/gradiumvoice:LFZvm12tW_z0xfGo

如果语音策略禁用了覆盖，这些指令会被接收但忽略。

输出格式

运行时根据目标表面选择输出格式。目前该提供商不支持其他格式。

目标表面	格式	文件扩展	采样率	语音笔记标记
标准音频	wav	.wav	提供商决定	否
语音笔记	opus	.opus	提供商决定	是
电话	ulaw_8000	n/a	8 kHz	n/a

自动选择顺序

在已配置的 TTS 提供商中，Gradium 的自动选择顺序为 30。当 messages.tts.provider 未固定时，OpenClaw 如何选择活跃提供商，请参见 文本转语音。

常见问题

Gradium API Key 报错怎么解决？

检查 apiKey 配置或 GRADIUM_API_KEY 环境变量是否正确设置。确保密钥有效且在 Gradium 控制台有足够配额。运行 openclaw doctor 验证配置。

语音覆盖不生效怎么办？

确认当前的语音策略（speech policy）允许语音覆盖。如果策略禁用了覆盖，即使消息中包含 /voice 等指令标记也不会切换声音。

输出音频格式不对怎么办？

输出格式由目标表面自动决定，不可手动配置。例如，标准聊天界面会输出 WAV，语音笔记场景输出 Opus，电话场景输出 8 kHz u-law。