Xiaomi TTS OpenClaw Plugin

将 Xiaomi MiMo mimo-v2-tts 接入为 OpenClaw speech provider 的独立插件。

Overview

这个项目为 OpenClaw 提供一个可注册的语音合成 provider: xiaomi-tts。

它当前聚焦于一个尽量小而稳定的集成面：

• 注册独立 speech provider: xiaomi-tts
• 调用 Xiaomi /v1/chat/completions 接口完成 TTS
• 固定使用 stream: false
• 支持 wav 和 mp3
• 兼容格式别名 wave、mpeg、mpeg3
• 支持 voice、style 和本地 voices 目录

Features

• 最小依赖，适合作为独立插件项目维护
• 同时兼容较新的 providerConfig 传参和旧的 OpenClaw 配置结构
• 本地校验输出格式，避免把非法格式请求直接打到远端
• 提供 listVoices()，可返回配置中的 voice 目录和当前已选 voice
• 不依赖真实 Xiaomi API key 即可运行测试

Compatibility

• OpenClaw Plugin API: >=2026.3.24-beta.2
• OpenClaw Gateway: >=2026.3.24-beta.2
• Xiaomi model default: mimo-v2-tts

Project Status

当前处于可用的早期版本，适合本地集成、验证和继续扩展。

已实现：

• isConfigured
• resolveConfig
• synthesize
• listVoices

暂未实现：

• streaming
• telephony
• STT
• opus / pcm 本地转码
• 远端动态拉取 voice 列表

Repository Structure

.
├── index.ts
├── openclaw.plugin.json
├── package.json
└── src
    ├── client.ts
    ├── provider.test.ts
    ├── speech-provider.ts
    └── types.ts

Installation

1. 将仓库放到本地插件目录中，例如：

git clone <your-repo-url> xiaomi-tts-openclaw-plugin
cd xiaomi-tts-openclaw-plugin

2. 在 OpenClaw 配置中注册插件入口。
3. 配置 XIAOMI_API_KEY。
4. 将消息 TTS provider 指向 xiaomi-tts。

Install via OpenClaw CLI

发布到 ClawHub 或 npm 之后，可以直接通过 OpenClaw CLI 安装：

openclaw plugins install openclaw-xiaomi-tts

如果你想显式指定 ClawHub 来源，也可以使用：

openclaw plugins install clawhub:openclaw-xiaomi-tts

Quick Start

下面是一个适合本地调试且当前运行时可生效的配置示例：

{
  env: {
    XIAOMI_API_KEY: "your-key"
  },
  plugins: {
    entries: {
      "xiaomi-tts": {
        enabled: true
      }
    }
  },
  messages: {
    tts: {
      enabled: true,
      provider: "xiaomi-tts",
      providers: {
        "xiaomi-tts": {
          baseUrl: "https://api.xiaomimimo.com/v1",
          model: "mimo-v2-tts",
          format: "mp3",
          voice: "default_zh",
          style: "温柔讲述风",
          audioTags: {
            enabled: true,
            mode: "auto"
          },
          voices: [
            {
              id: "mimo_default",
              name: "MiMo-Default",
              description: "官方内置默认音色"
            },
            {
              id: "default_zh",
              name: "MiMo-Chinese Female Voice",
              locale: "zh-CN",
              gender: "female",
              description: "官方内置中文女声"
            },
            {
              id: "default_en",
              name: "MiMo-English Female Voice",
              locale: "en-US",
              gender: "female",
              description: "官方内置英文女声"
            }
          ]
        }
      }
    }
  }
}

Configuration

Placement Rules

• 运行时实际生效的 TTS 参数统一放在 messages.tts.providers.xiaomi-tts
• plugins.entries.xiaomi-tts 只用于插件启用和安装信息，不作为 style、model、format、voice、baseUrl 的运行时来源
• 不要把 model、format、voice、baseUrl 这类字段直接平铺到 plugins.entries.xiaomi-tts 顶层

错误示例会导致 OpenClaw 报出：

plugins.entries.xiaomi-tts: Unrecognized keys: ...

Config Fields

Style Placement

OpenClaw 里 style 当前应配置在下面这个位置：

1. messages.tts.providers.xiaomi-tts.style

示例：

{
  messages: {
    tts: {
      provider: "xiaomi-tts",
      providers: {
        "xiaomi-tts": {
          style: "温柔讲述风"
        }
      }
    }
  }
}

说明：

• 插件会把这个值转成 Xiaomi 文档要求的 <style>...</style> 文本前缀
• model、format、voice、baseUrl、voices 也统一配置在 messages.tts.providers.xiaomi-tts
• plugins.entries.xiaomi-tts.config 不再作为这些运行时参数的来源
• 当前运行时 synthesize(req) 依赖 providerConfig
• 不再从 IDENTITY.md 的 Vibe 自动回填 style

Audio Tags

如果你希望插件先用 agent 大模型给文本加上音频标签，再送入 Xiaomi TTS，可以这样配置：

{
  messages: {
    tts: {
      provider: "xiaomi-tts",
      providers: {
        "xiaomi-tts": {
          style: "温柔讲述风",
          audioTags: {
            enabled: true,
            mode: "auto",
            unsafeRewriteCheck: false
          }
        }
      }
    }
  }
}

说明：

• audioTags 也统一配置在 messages.tts.providers.xiaomi-tts
• 插件会先调用 agent 大模型生成类似 （小声）、（停顿） 这样的标签，再叠加 <style>...</style> 前缀
• 默认会校验“去掉标签后是否仍等于原文”；不满足时自动回退到原文
• 如果你想临时放开这层限制，可以配置 audioTags.unsafeRewriteCheck: false
• 当前实现只支持 mode: "auto"
• 如果未显式配置 audioTags.provider / audioTags.model，插件会优先从 OpenClaw 当前 agent 配置里推断；在 Codex OAuth 场景下会优先使用 openai-codex/gpt-5.4，避免误落到 openai/gpt-5.4

Format Support

• 支持：wav、mp3
• 兼容别名：
  • wave -> wav
  • mpeg -> mp3
  • mpeg3 -> mp3
• 配置为其他格式时会在本地直接报错

Voice Catalog

插件支持 listVoices()，返回来源包括：

• 当前配置中的 voice
• 配置中的 voices 数组
• 一个内置 fallback voice: default

如果当前已选 voice 不在 voices 数组中，插件也会自动补入返回结果，避免 OpenClaw 侧出现“当前值不在目录里”的情况。

Xiaomi 官方文档当前列出的内置音色

说明：

• 以上表格来自 Xiaomi 当前公开文档
• 这不代表 Xiaomi 已提供可直接调用的 voice 列表 API
• 如果官方文档变更，这里的示例也需要同步更新

Development

Run Tests

npm test

当前测试覆盖：

• 默认配置解析
• 旧/新配置结构兼容
• voice 目录构建与去重
• 格式别名与格式校验
• 核心 TTS 参数从 providerConfig 读取
• base64 音频解码

Local Verification

建议的真实联调步骤：

1. 配置 XIAOMI_API_KEY
2. 在 OpenClaw 中设置 messages.tts.provider = "xiaomi-tts"
3. 通过 /tts 或语音回复链路执行端到端验证

Publishing

推荐先发布到 ClawHub，这样用户可以直接通过 openclaw plugins install 安装。

示例发布命令：

clawhub login
VERSION=$(node -p "require('./package.json').version")
COMMIT=$(git rev-parse HEAD)

clawhub package publish "$PWD" \
  --family code-plugin \
  --name openclaw-xiaomi-tts \
  --display-name "Xiaomi TTS" \
  --version "$VERSION" \
  --source-repo TeaBambooNGU/xiaomi-tts-openclaw-plugin \
  --source-commit "$COMMIT"

Known Limitations

• Xiaomi voice 列表当前不是通过远端接口动态拉取
• voices 目录需要由本地配置显式提供
• 仅支持 wav 和 mp3
• 当前请求体固定 stream: false

Reference

• Xiaomi MiMo Speech Synthesis 文档： https://platform.xiaomimimo.com/docs/usage-guide/speech-synthesis.md