Fish Audio TTS Setup: Hosted and Local

OpenClaw integrates with Fish Audio through two separate paths:

Hosted S2.1 is delivered by the fish-audio speech provider on the Gateway. It functions across channels, voice notes, Talk, and telephony.
Local S2 Pro runs within the native macOS app via the existing mlx Talk provider. Everything stays on the Mac, and no Fish API key is needed.

Warning

The S2 Pro weights available for download fall under the Fish Audio Research License. Personal, research, and non-commercial evaluation are permitted; commercial usage demands a separate Fish Audio license. The hosted API operates according to Fish Audio's service terms.

Hosted S2.1

Add the fish-audio-speech plugin:

openclaw plugins install @openclaw/fish-audio-speech

The plugin id is fish-audio-speech. The provider and TTS configuration id stay as fish-audio.

Grab an API key from the Fish Audio API Keys page:

export FISH_API_KEY="..."

Next, set up the provider:

{
  tts: {
    auto: "tagged",
    provider: "fish-audio",
    providers: {
      "fish-audio": {
        apiKey: "${FISH_API_KEY}",
        model: "s2.1-pro",
        // Optional saved or public Fish Audio voice model id:
        speakerVoiceId: "802e3bc2b27e49c2995d23ef70e6ac89",
        latency: "balanced",
      },
    },
  },
}

speakerVoiceId is not required. When omitted, Fish Audio falls back to its default voice. FISH_AUDIO_API_KEY is also recognized for compatibility with existing community plugins, though FISH_API_KEY remains the standard Fish SDK environment variable.

Hosted models

Model	Use
`s2.1-pro`	Default. Production S2.1 service with the hosted service guarantees attached to your plan.
`s2.1-pro-free`	Promotional S2.1 access through August 31, 2026; no TTFA or DPA guarantees. Select it explicitly while active.
`s2-pro`	Previous S2 generation.
`s1`	Previous generation with parenthesized emotion controls.

For ordinary audio the provider requests MP3, for native voice notes Opus at 48 kHz, and for telephony raw PCM at 8 kHz. On Discord voice, OpenClaw consumes Fish Audio's chunked HTTP response as it arrives rather than waiting for the full clip.

Expressive speech

S2 and S2.1 accept inline natural-language tags. Insert them into the spoken text:

[whisper] Keep this between us. [pause] [excited] We shipped it!

Frequently used tags include [whisper], [laughing], [excited], [sad], [pause], and free-form instructions such as [professional broadcast tone].

Voice selection and cloning

To inspect the active provider, use /tts status; for a single clip, use /tts audio <text>. Fish voice ids can originate from your own trained voices or the public Fish voice library. OpenClaw shows your voices first, then a bounded page of popular public voices.

The speech provider consumes existing voice ids; it does not upload recordings or generate voice models. Voice creation is a separate consent-sensitive action in the Fish Audio app or API.

Local S2 Pro on macOS

The native macOS app includes an isolated MLX TTS helper. On Apple silicon, direct the existing mlx Talk provider at the 8-bit Fish conversion:

{
  talk: {
    provider: "mlx",
    providers: {
      mlx: {
        modelId: "mlx-community/fish-audio-s2-pro-8bit",
      },
    },
  },
}

The first utterance downloads roughly 6.8 GB of model and codec data. OpenClaw holds one selected MLX model resident for repeated utterances, then releases it after five idle minutes, app shutdown, or memory pressure.

Local reference voice

When the Gateway and macOS app share the same filesystem, set up a clean 10, 30 second reference recording and its exact transcript:

{
  talk: {
    provider: "mlx",
    providers: {
      mlx: {
        modelId: "mlx-community/fish-audio-s2-pro-8bit",
        referenceAudioPath: "/Users/example/Voices/reference.wav",
        referenceText: "The exact words spoken in the reference recording.",
      },
    },
  },
}

referenceAudioPath is resolved on the Mac running the native app, not on a remote Gateway. The file stays local: the app passes it only to its isolated MLX helper. Local Fish output streams as PCM into Talk playback, so speech can begin before a long generation completes.

Note

Local MLX currently applies only to native macOS Talk. Other channels and clients use the Gateway-selected hosted speech provider. iOS and Android retain their existing native/system and Gateway Talk paths.

Troubleshooting

Fish Audio API key missing: set FISH_API_KEY or tts.providers.fish-audio.apiKey.
HTTP 401: verify the API key at Fish Audio.
HTTP 402: the selected hosted model requires available credits or plan access.
Local model falls back to the system voice: confirm Apple silicon, free disk space, and the exact Hugging Face model id.
Local clone does not match: use clean single-speaker audio and make referenceText match it exactly.

See the Fish Audio TTS API and Fish Audio Research License.