Configure Gradium Text-to-Speech in OpenClaw

Gradium serves as a text-to-speech provider for OpenClaw. It produces three kinds of audio: standard WAV replies, Opus output that works with voice notes, and 8 kHz u-law audio for telephony surfaces.

Install plugin

Gradium ships as an official external plugin. To add it:

openclaw plugins install @openclaw/gradium-speech

If a Gateway is already running, the installation is picked up without a restart. If not, it applies the next time the process starts. Refer to Apply changes and inspect.

Setup

Generate a Gradium API key, then make it available either through an env var or the config key. When both are set, the config key wins.

Env var

export GRADIUM_API_KEY="<your-gradium-api-key>"

Config key

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

Config

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

The target surface decides the output format on its own (refer to Output), and openclaw.json offers no way to change it.

Voices

Per-message voice override

Provided the active speech policy permits voice overrides, you can swap voices mid-stream using a directive token. The forms below are interchangeable, and each expects a provider-native voice id:

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

Should the speech policy forbid voice overrides, the directive still gets consumed, but nothing happens.

Output

The target surface determines which output format is produced; no other formats are synthesized by this provider.

Auto-select order

When several TTS providers are configured, Gradium sits at position 30 in the auto-select order. For details on how OpenClaw chooses the active provider whenever tts.provider is left unpinned, see Text-to-Speech.

Related

• Text-to-Speech
• Media Overview