灵犀Claw实战：从零搭建一个会自我进化的AI Agent（九）让灵犀开口说话——MiMo TTS 实战

本系列记录用WPS灵犀Claw平台从零搭建一个具备完整记忆闭环和自我改进能力的AI Agent的全过程。每个专题一篇，由浅入深。

开篇引言

前八篇搭建了一个完整的Agent系统——记忆闭环、自我改进、智能日记、生图能力、云文档管理。但有一个关键能力一直没有覆盖：让Agent开口说话。

文字回复和语音回复的体验差距是巨大的。当Agent能用声音读出日记、用专属音色和你聊天、甚至在你忙的时候"说"给你听，它就从"工具"变成了"伙伴"。

本篇介绍如何用小米MiMo V2.5 TTS让灵犀Claw开口说话。我们会参考官方文档讲清楚核心能力，再分享实战中如何封装成Skill，让Agent稳定调用同一套声音。

至于为什么用MiMo，想必最近玩agent的没少薅雷总家羊毛吧(#^.^#)

MiMo V2.5 TTS 是什么

MiMo V2.5 TTS是小米于2026年4月发布的语音合成模型系列，是小米MiMo大模型生态的一部分。它提供了三款各司其职的模型，覆盖从开箱即用到深度定制的全部需求。

mimo-v2.5-tts（预置音色）：内置12种精品音色（中英文各6种），无需任何配置即可使用。支持唱歌模式和流式输出。适合快速验证和通用场景。

mimo-v2.5-tts-voicedesign（音色设计）：通过文本描述自动生成音色，无需音频样本。适合需要独特音色但没有参考音频的场景。

mimo-v2.5-tts-voiceclone（音色克隆）：基于一段参考音频（mp3/wav，不超过10MB）精准复刻音色。适合需要特定人物声音的场景，也是本系列项目中主力使用的模式。

三款模型互斥：预置音色不支持设计和克隆，音色设计不支持预置和克隆，音色克隆不支持预置和设计。选择时根据需求确定即可。

快速上手：5行代码让灵犀说第一句话

MiMo TTS采用OpenAI兼容API，如果你用过OpenAI的接口，上手几乎零成本。以下是最简单的调用方式：

import os
from openai import OpenAI
import base64

client = OpenAI(
    api_key=os.environ.get("MIMO_API_KEY"),
    base_url="https://api.xiaomimimo.com/v1"
)

completion = client.chat.completions.create(
    model="mimo-v2.5-tts",
    messages=[
        {"role": "user", "content": "用轻快活泼的语气说话"},
        {"role": "assistant", "content": "你好呀，我是你的AI助手，很高兴认识你！"}
    ],
    audio={"format": "wav", "voice": "冰糖"}
)

audio_bytes = base64.b64decode(completion.choices[0].message.audio.data)
with open("output.wav", "wb") as f:
    f.write(audio_bytes)

这段代码做了三件事：指定模型为mimo-v2.5-tts、在user message中描述语气风格、在assistant message中放要合成的文本。返回的音频数据以Base64编码嵌入在响应中，解码后写入文件即可播放。

需要注意：合成文本必须放在role为assistant的消息中，不能放在user消息里。user消息是可选的，用于控制语气风格，不会出现在合成的语音中。

风格控制：让声音有情绪

MiMo V2.5 TTS提供了两种风格控制方式，可以单独使用也可以组合使用。

自然语言控制（user message）：在user消息中用自然语言描述想要的语音风格。这是最直观的方式，模型能理解"用轻快上扬的语调向领导报喜"这样的指令。官方还支持一种"导演模式"——从角色、场景、指导三个维度全方位刻画人物声线，适合角色配音等对语音表演要求较高的场景。

音频标签控制（assistant文本内嵌）：在合成文本中嵌入风格标签和音频标签，对语音进行精细控制。开头用(风格)标签指定整体基调，中间用[音频标签]控制语速、情绪、呼吸、笑声等细节。

两种控制方式可以叠加使用：user message定整体基调，assistant文本中的标签做局部微调。但需要注意，voiceclone模式下不建议使用自然语言控制（后面会详细说明）。

音色克隆：让灵犀拥有专属声音

音色克隆是MiMo TTS最强大的能力。只需一段参考音频（建议10-15秒，清晰的人声），就能复刻出任意音色。

调用方式与预置音色类似，只是模型换为mimo-v2.5-tts-voiceclone，并在audio参数中传入voice_file指定参考音频路径。

voiceclone模式有一个关键原则：越简单越好。 不需要在user message中写风格描述，也不需要加--context和--speed参数。参考音频本身已经包含了音色和说话习惯的全部信息，额外添加风格控制反而会破坏音色的自然度。

音频标签可以有限使用，但必须遵循三条铁律：标签不能放在开头（会出错或糊音）、只能放在中间（效果最自然）、不能放在末尾（会产生杂音）。可用的标签包括(停顿)(长停顿)(耳语)(轻声)(叹气)(拖音)(欲言又止)(碎碎念)(笑)(清嗓子)。情绪词、肢体动作描述、场景描述等标签在voiceclone模式下禁用。

封装成Skill：固化声音，稳定调用

这是本篇最有实战价值的部分。在灵犀Claw中，让Agent稳定调用同一套声音的关键是将TTS调用封装成一个Skill。

一个标准的灵犀Claw Skill包含三个部分：SKILL.md（使用说明）、scripts/（脚本代码）、references/（参考文档）。我们以mimo-tts skill为例，拆解封装思路。

第一步：编写调用脚本。将API调用封装成Python脚本，通过命令行参数接收文本和输出路径。这样Agent调用时只需执行subprocess.run，不需要处理OpenAI客户端的导入和配置细节。

第二步：固化音色配置。将参考音频路径、API Key读取逻辑、默认参数（如voiceclone模式不加context）全部写在脚本中。Agent调用时只需要传入文本，不需要关心底层配置。这就是"固化"的本质——把"用什么声音说话"变成Skill的默认行为。

第三步：编写SKILL.md。在SKILL.md中写明模型的加载方式、参数说明、常见错误处理。Agent在调用前会读取SKILL.md了解如何使用，所以文档质量直接影响调用成功率。

第四步：注册到Agent配置。将Skill放到skills/目录下，Agent启动时自动加载。之后Agent需要生成语音时，直接调用skill脚本即可。

这套封装思路的核心价值在于：Agent不需要理解TTS的技术细节。它只需要知道"我要说这句话，用我的声音说出来"——剩下的由Skill处理。这也意味着，换一套声音只需要替换参考音频，Agent代码完全不需要改动。

踩坑清单

问题1：voiceclone模式下加context导致音色失真根因：风格控制指令与参考音频的音色特征冲突，模型试图"理解"指令而偏离了原始音色解法：voiceclone模式绝对不加--context和--speed，让模型完全依赖参考音频

问题2：标签放在开头导致糊音根因：voiceclone模型对开头位置的标签处理不稳定，可能覆盖参考音频的特征解法：标签只放在文本中间位置，开头和末尾都不放

问题3：API返回401错误根因：MIMO_API_KEY未设置或格式不对。TTS的API Key独立于模型推理Key，即使mimo-v2-pro能正常调用，TTS仍需单独配置解法：确认环境变量MIMO_API_KEY已正确设置，或从config.json读取

问题4：长文本合成效果不佳根因：超过2500字的文本可能导致模型处理不稳定解法：分段合成后用ffmpeg拼接：先分别生成各段wav，再用concat协议合并

问题5：流式输出无返回根因：网络波动导致流式连接中断解法：重试或改用非流式模式。流式输出需指定format为pcm16，合成后用numpy+ soundfile拼接

问题6：合成文本放在user消息中根因：MiMo TTS要求合成文本在assistant消息中，user消息仅用于风格控制解法：确保role为assistant的消息中包含待合成文本

与前几篇的联动

语音能力不是孤立的，它可以与前面各篇的能力深度结合：

系列05（Cherry Diary）：日记生成后自动合成语音，用户可以直接"听"日记，而不是读文字。这是语音能力最自然的落地场景。

系列07（生图Prompt）：生成的图片配上语音解说，形成完整的图文声内容。例如生成一张风景图后，用温柔的声音描述画面内容。

系列08（云文档API）：合成的语音文件通过云文档API上传保存，形成可分享的语音内容。用户可以在云文档中直接播放。

系列06（Self-Improving）：语音生成的调用记录和效果反馈可以进入自我改进系统，持续优化语音合成的文本风格和标签使用策略。

系列进度

（一）总体架构：系统全景、Skill清单、设计哲学

（二）实时记忆：三层记忆架构、"先沉淀再回复"机制

（三）Dreaming：三阶段记忆沉淀、时间验证、碎片管理

（四）Memory Consolidation：每周深度整理、去重合并、Token控制

（五）Cherry Diary：智能日记：数据采集+提示词架构+可选多媒体

（六）Self-Improving：纠错-偏好-反思-衰减完整闭环

（七）生图Prompt：铁律、Seedream技巧、版本迭代、记忆联动

（八）云文档API：三条路径、三步上传协议、选型指南、踩坑清单

（九）MiMo TTS：三款模型、风格控制、音色克隆、Skill封装、踩坑经验

最后：还请开发组早日让灵犀能在渠道直接推送原生语音消息啊！