Fish Audio

OpenClaw 以两种不同方式支持 Fish Audio：

• 托管 S2.1 通过 Gateway 上的 fish-audio 语音提供商运行，并适用于频道、语音消息、Talk 和电话。
• 本地 S2 Pro 通过现有的 mlx Talk 提供商在原生 macOS 应用内运行。它保留在 Mac 上，并且不需要 Fish API 密钥。

托管 S2.1¶

安装 fish-audio-speech 插件：

openclaw plugins install @openclaw/fish-audio-speech

插件 id 为 fish-audio-speech。提供商和 TTS 配置 id 仍为 fish-audio。

从 Fish Audio API Keys 页面设置 API 密钥：

export FISH_API_KEY="..."

然后配置提供商：

{
  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 是可选的。如果没有它，Fish Audio 会使用其默认语音。 FISH_AUDIO_API_KEY 也被接受，以兼容现有社区插件，但 FISH_API_KEY 是 Fish SDK 的规范环境变量。

托管模型¶

该提供商为普通音频请求 MP3，为原生语音消息请求 48 kHz 的 Opus，为电话请求 8 kHz 的原始 PCM。对于 Discord 语音，OpenClaw 会在 Fish Audio 的分块 HTTP 响应到达时消费它，而不是等待整个片段。

表现力语音¶

S2 和 S2.1 接受内联自然语言标签。将它们放在要朗读的文本中：

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

常见标签包括 [whisper]、[laughing]、[excited]、[sad]、[pause]，以及自由格式指令，例如 [professional broadcast tone]。

语音选择与克隆¶

使用 /tts status 检查当前活动的提供商，使用 /tts audio <text> 生成一次性片段。Fish 语音 id 可以来自你自己训练的语音或公共 Fish 语音库。OpenClaw 会先列出你的语音，然后列出一页有界的热门公共语音。

语音提供商消费现有语音 id；它不会上传录音或创建语音模型。语音创建是 Fish Audio 应用或 API 中另一个涉及同意的敏感操作。

macOS 上的本地 S2 Pro¶

原生 macOS 应用捆绑了一个隔离的 MLX TTS 辅助程序。在 Apple silicon 上，将现有的 mlx Talk 提供商指向 8 位 Fish 转换：

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

第一次语音会下载约 6.8 GB 的模型和编解码器数据。OpenClaw 会保留一个已选 MLX 模型常驻，用于重复语音，然后在五分钟空闲、应用关闭或内存压力后卸载它。

本地参考语音¶

当 Gateway 和 macOS 应用共享同一文件系统时，配置一段干净的 10–30 秒参考录音及其精确转录文本：

{
  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 在运行原生应用的 Mac 上解析，而不是在远程 Gateway 上。文件保持本地：应用只将其传递给其隔离的 MLX 辅助程序。本地 Fish 输出以 PCM 流式传输到 Talk 播放中，因此语音可以在长时间生成完成前开始。

故障排除¶

• Fish Audio API key missing：设置 FISH_API_KEY 或 tts.providers.fish-audio.apiKey。
• HTTP 401：在 Fish Audio 处验证 API 密钥。
• HTTP 402：所选托管模型需要可用额度或套餐访问权限。
• 本地模型回退到系统语音：确认 Apple silicon、可用磁盘空间以及精确的 Hugging Face 模型 id。
• 本地克隆不匹配：使用干净的单说话人音频，并使 referenceText 与其完全匹配。

参见 Fish Audio TTS API 和 Fish Audio Research License。