voice

name	voice
description	Send voice/song audio through the active Nako messaging channel — voice.sh does plain TTS (MiniMax or Volcengine); sing.sh generates a full song with melody via MiniMax music-2.6
allowed-tools	Bash(curl:*) Bash(jq:*) Bash(xxd:*) Bash(base64:*) Bash(uuidgen:*) Bash(sleep:*) Bash(ffprobe:*) Bash(*/voice.sh:*) Bash(*/sing.sh:*) Bash(*/setup.sh:*) Read Write

Voice — 语音消息

将文本转为语音，并通过当前 Nako 消息通道发送。支持 MiniMax 和火山引擎两个 TTS 引擎。

何时使用

用户说以下内容时触发：

• "发个语音" / "说句话给我听" / "用语音回复"
• "send a voice message" / "speak to me"
• "我想听你的声音" / "语音消息"
• 讲故事、读诗、晚安问候等适合用声音表达的场景

不要用于：普通文字对话、技术说明、超长文本（>500 字请分段）

在飞书/微信/ACP 会话里，语音和唱歌必须用 voice.sh / sing.sh 且 channel 填 cc-connect。不要调用 OpenClaw 原生 tts，那只会生成 webchat 媒体，飞书/微信收不到。

cc-connect/ACP 会话里即使看到 messageProvider=webchat，也不要设置 NAKO_OUTPUT_MODE=webchat，不要把 channel 填 webchat。语音和唱歌统一用 NAKO_OUTPUT_MODE=acp 与 channel cc-connect，这样脚本才能投递到当前飞书/微信 session。

说话 vs 唱歌：选对脚本

场景	用	说明
说话（朗读、问候、讲故事、撒娇）	voice.sh	纯 TTS，秒级合成
唱歌（有旋律的歌曲、写歌送给用户、生日快乐歌）	sing.sh	MiniMax music-2.6，带伴奏和旋律，10–60 秒生成

判断要点：

• 用户说「唱一首/给我唱/写首歌/来段 rap/唱给我听/生日歌」→ sing.sh
• 用户说「读一下/发语音/说一句/念给我听」→ voice.sh
• 内容含 [verse] [chorus] 等结构标签或明显是歌词格式 → sing.sh
• 犹豫时默认 voice.sh（更快、更便宜）

快速使用

bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/voice.sh" "<文本>" "<频道ID>" [provider] [voice_id] [speed]

参数	必须	默认值	说明
text	是	—	要合成的文本，建议 500 字以内
channel	是	—	飞书 chat_id（oc_xxx）或 open_id（ou_xxx）；Hermes/cc-connect/ACP 会话用 cc-connect 自动路由到当前活跃会话（feishu 只作为旧别名兼容）
provider	否	auto	minimax / volcengine / auto（按 key 自动选择）
voice_id	否	按引擎默认	音色 ID，见下方音色表
speed	否	1.0	语速倍率 0.5–2.0

示例

# MiniMax 甜美女声
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/voice.sh" "主人大人早上好呀！" "oc_xxx" minimax female-tianmei 1.0

# 火山引擎 爽快女声
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/voice.sh" "今天天气真不错呢！" "oc_xxx" volcengine zh_female_shuangkuaisisi_moon_bigtts 1.0

# 慢速温柔语音（适合晚安）
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/voice.sh" "晚安，做个好梦哦……" "oc_xxx" minimax female-tianmei 0.85

# Hermes / cc-connect 当前会话（飞书、微信等都走当前活跃会话）
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/voice.sh" "主人大人，我在这里哦。" "cc-connect" auto female-tianmei 1.0

微信/iLink 目前不支持外部 bot 主动发送原生语音气泡；微信通道会把 MP3 作为文件附件发送。

TTS 引擎

MiniMax（推荐）

• 模型：speech-02-hd
• 音频：MP3 32kHz 128kbps
• 返回 duration，无需 ffprobe
• 获取 key：platform.minimaxi.com

音色 ID	描述	推荐场景
female-tianmei	甜美女声 （默认）	日常、撒娇、问候
female-shaonv	少女声	元气、兴奋
female-yujie	御姐声	认真、冷酷
female-chengshu	成熟女声	沉稳、叙述

火山引擎（备选）

• API：V3 HTTP Chunked（openspeech.bytedance.com）
• 模型版本：seed-tts-1.0（默认），可切换 seed-tts-2.0
• 获取 key：console.volcengine.com/speech/new

音色 ID	描述
zh_female_shuangkuaisisi_moon_bigtts	爽快思思 （默认）
zh_female_cancan_mars_bigtts	灿灿（活泼）
zh_female_gaolengyujie_moon_bigtts	高冷御姐
zh_female_sajiaonvyou_moon_bigtts	撒娇女友
zh_female_tianmeixiaoyuan_moon_bigtts	甜美小源

更多音色见 火山引擎音色列表

唱歌 — sing.sh

bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/sing.sh" "<歌词>" "<频道ID>" ["<风格描述>"] ["<model>"]

参数	必须	默认	说明
lyrics	是	—	歌词。支持段落标签 [intro] [verse] [pre chorus] [chorus] [bridge] [outro]，用 \n 换行
channel	是	—	chat_id (oc_xxx) / open_id (ou_xxx)；Hermes/cc-connect/ACP 会话用 cc-connect 自动路由
style_prompt	否	Indie pop, gentle, warm female vocal, acoustic guitar	风格描述：流派+情绪+乐器+人声性别
model	否	music-2.6	music-2.6 或 music-2.6-free（免费版配额有限）

歌词结构建议

[verse]
第一段主歌第一行
第一段主歌第二行
[chorus]
副歌高潮第一行
副歌高潮第二行
[bridge]
过桥段
[outro]
收尾

示例

# 中文抒情
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/sing.sh" "[verse]\n月色洒在窗台\n思念像潮水漫来\n[chorus]\n想你在每个夜晚\n想你在每次梦醒" "oc_xxx" "Chinese ballad, soft piano, female vocal, emotional"

# 英文流行
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/sing.sh" "[verse]\nStreetlights flicker, the night breeze sighs\n[chorus]\nPushing the wooden door, the aroma spreads" "ou_xxx" "Indie folk, acoustic guitar, melancholic"

# 生日歌（即兴写词）
bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/sing.sh" "[verse]\n亲爱的小夜今天生日\n愿望写在蛋糕上\n[chorus]\n生日快乐生日快乐\n每一天都要笑开花" "oc_xxx" "Upbeat pop, cheerful, warm female voice"

注意

• 生成耗时 10–60 秒，发消息前可先说「稍等，我写一首给你～」安抚用户
• 歌词最好 30–400 字，太短模型会补白、太长会截断
• 风格描述用英文更精确（MiniMax 训练数据以英文 prompt 为主）
• 输出音频默认 44.1kHz / 256kbps MP3，比 TTS 音质高很多
• 失败时看 stderr 的 status_msg，常见 lyrics_too_short / invalid_model / 配额耗尽

环境变量

Hermes/cc-connect 优先读取 $NAKO_SKILLS_DIR/.env、~/.hermes/.env 和当前 agent 的 skills/.env；OpenClaw 仍兼容 openclaw.json → skills.entries.voice.env。

飞书凭据

变量	来源	说明
FEISHU_APP_ID	飞书开放平台	OpenClaw 原生直连飞书时必需；Hermes/cc-connect 下由 QR 绑定写入 ~/.cc-connect/config.toml，可同步镜像到 <workspace>/skills/.env
FEISHU_APP_SECRET	飞书开放平台	同上

Hermes/cc-connect 场景不要仅凭 <workspace>/skills/.env 里的空 FEISHU_APP_ID 判断飞书未配置；先确认 cc-connect project 是否已绑定飞书。

MiniMax（至少配一组 TTS）

变量	说明
MINIMAX_API_KEY	MiniMax API 密钥
MINIMAX_GROUP_ID	MiniMax 分组 ID

火山引擎（可选）

变量	说明
VOLCENGINE_API_KEY	火山引擎新版控制台 API Key
VOLCENGINE_RESOURCE_ID	模型版本（默认 seed-tts-1.0）

安装

首次安装运行安装脚本，交互式引导配置 API Key：

bash "${NAKO_SKILLS_DIR:-$HOME/.openclaw/skills}/voice/scripts/setup.sh"

脚本会：

1. 检查系统依赖（jq, curl, ffprobe）
2. 引导输入 TTS API Key
3. 自动从当前 runtime env 读取飞书凭据
4. 写入当前 runtime skill env
5. 发送测试语音验证

工作原理

文本 → TTS API → MP3 音频
  → 飞书上传（file_type=opus, 含 duration）
  → 飞书发送（msg_type=audio）
  → 用户收到可播放的语音消息

关键细节：

• 上传时 file_type 必须设为 opus（即使文件是 mp3），飞书服务端转码
• 上传时必须传 duration（毫秒），否则语音无法播放
• MiniMax 返回十六进制编码音频（xxd 解码），火山引擎返回 base64
• 临时文件 10 分钟后自动清理

使用建议

• 文本口语化，短句为主，加逗号和省略号控制节奏
• 亲密/感性内容用慢速（0.8–0.9）
• 日常用正常速度（1.0）
• 兴奋场景可稍快（1.1–1.2）
• 语音消息前后配合文字，如"给你录了一段语音哦～"
• 不要每条消息都发语音，特殊场景才有仪式感

错误排查

问题	原因	解决
MiniMax error	API key 或 Group ID 错误	检查 $NAKO_SKILLS_DIR/.env 或当前 runtime env 里的 MINIMAX_API_KEY 和 MINIMAX_GROUP_ID
Volcengine resource mismatch	音色和模型版本不匹配	seed-tts-1.0 音色用 seed-tts-1.0，2.0 同理
Upload failed	飞书 token 过期或权限不足	OpenClaw 原生模式检查 FEISHU_APP_ID/SECRET；Hermes/cc-connect 检查 cc-connect Feishu QR 绑定和 ~/.cc-connect/config.toml
语音无法播放	未传 duration	确认上传时 duration 参数正确传入
Bot can NOT be out of chat	飞书 App ID 和聊天不匹配	使用对应 agent 的飞书 App ID