前言¶

让 Agent 产出语音，常见做法是自己搭一个 TTS 服务，再写一段调用与文件落盘逻辑。对多数只需要”把一段话念出来”的场景来说，这条路偏重：要选引擎、要配密钥、要处理音频格式。Edge TTS 这个 Skill 走的是另一条路：直接调用微软 Edge 的在线神经网络 TTS 服务，不需要 API Key，装完就能在脚本里把文本变成 MP3。下面介绍它的能力、安装方式和可直接复现的用法。

这是什么¶

Edge TTS 是一个基于通用 SKILL.md 格式的 Agent 技能，来源是 clawhub 上的 @i3130002/edge-tts，发布者 i3130002，当前版本 2.0.0，许可证 MIT-0，分类为 design-media。它的定位很明确：把文本转成语音，并支持多音色、多语言、语速/音量/音调调节，以及字幕生成。据 SkillHub 页面的抓取资料，评分为 100000，下载 39927 次，安装 5028 次，标签中 requires_api_key=false，即不需要密钥。上游仓库是 https://clawhub.ai/i3130002/edge-tts 。

一句话概括：当你想让 Agent”念”而不是”写”的时候，用它。

核心功能¶

已核实的能力有这些：

1、文本转语音。底层是 node-edge-tts 这个 npm 包，走微软 Edge 的在线神经网络 TTS 服务。资料里特别注明用的是”updated, working authentication”，说明认证方式已经被维护过。

2、多音色与多语言。内置常用音色列表，英文有 en-US-MichelleNeural、en-US-AriaNeural、en-US-GuyNeural、en-GB-SoniaNeural、en-GB-RyanNeural，其他语言包括 es-ES-ElviraNeural、fr-FR-DeniseNeural、de-DE-KatjaNeural、ja-JP-NanamiNeural、zh-CN-XiaoxiaoNeural、ar-SA-ZariyahNeural。音色名以 Neural 结尾的属于神经网络音色，音质高于 Standard 音色。完整列表用 --list-voices 查。

3、语速、音量、音调三项调节。语速按百分比格式，如 +10%、-20%，也支持 default。

4、字幕生成。可输出 JSON 格式的字幕文件，带词级时间轴。

5、输出格式可选。提供三档 MP3 质量：audio-24khz-48kbitrate-mono-mp3（标准，适合语音消息）、audio-24khz-96kbitrate-mono-mp3（高质量，适合演示）、audio-48khz-96kbitrate-stereo-mp3（最高质量，适合专业音频）。

6、触发词过滤。识别到 tts 相关关键词时，会先把这些词从文本里滤掉再转换，避免把”tts”本身念出来。

安装与启用¶

安装分两层：先装技能，再装技能自带的脚本依赖。

技能本体的安装命令，上游仓库给出的是 ClawHub 的 CLI：

$ openclaw skills install @i3130002/edge-tts

装完后，技能自带的 Node 脚本还需要单独装依赖：

cd /home/user/clawd/skills/public/edge-tts/scripts
npm install

这一步会装两个包：node-edge-tts（TTS 库）和 commander（命令行参数解析）。路径里的 /home/user/clawd/skills/public/edge-tts/scripts 是上游文档里写的示例路径，实际位置取决于你本地的技能安装目录，以 openclaw skills install 的落盘位置为准。

需要说明一处口径差异：任务线索里写的是 uvx edge-tts，但已抓取资料和上游仓库页面都指向 node-edge-tts，没有出现 uvx 相关的命令或说明。本文以可核实的上游资料为准，不采用 uvx 那条。

关于 Agent 侧的接入方式，上游文档描述的是 ClawHub / Clawdbot 的路径：技能内提供一个内置 tts 工具，工具返回 MEDIA: 路径，由 Clawdbot 把音频投递到当前会话通道。如果用的是 Cursor 或 Codex CLI，官方资料没有给出对应的接入说明，这里不推测。

典型用法¶

分两种用法：简单场景直接调工具，要精细控制就调脚本。

第一种，Agent 内置工具，适合只想把一段话念出来：

tts("Your text to convert to speech")
// Returns: MEDIA: /path/to/audio.mp3

工作流是：识别 tts 意图 → 调 tts 工具 → 拿到 MEDIA: 路径 → 由 Agent 投递音频。

第二种，命令行脚本，参数全部可配。先切到脚本目录：

cd scripts
npm install
node tts-converter.js "Your text" --voice en-US-AriaNeural --rate +10% --output output.mp3

上面这条把一段英文文本用 en-US-AriaNeural 音色、语速加快 10% 合成，输出到 output.mp3。tts-converter.js 是主转换脚本，参数如下：

--voice, -v : Voice name (default: en-US-AriaNeural)
--lang, -l : Language code (e.g., en-US, es-ES)
--format, -o : Output format (default: audio-24khz-48kbitrate-mono-mp3)
--pitch : Pitch adjustment (e.g., +10%, -20%, default)
--rate, -r : Rate adjustment (e.g., +10%, -20%, default)
--volume : Volume adjustment (e.g., +0%, -10%, default)
--save-subtitles, -s : Save subtitles as JSON file
--output, -f : Output file path (default: tts_output.mp3)
--proxy, -p : Proxy URL (e.g., http://localhost:7890)
--timeout : Request timeout in milliseconds (default: 10000)
--list-voices, -L : List available voices

注意 --format, -o 与 --output, -f 的缩写容易记混：前者是音频格式，后者是输出路径。

如果想让常用参数持久化，用配置管理脚本：

node config-manager.js --set-voice en-US-AriaNeural
node config-manager.js --set-rate +10%
node config-manager.js --get
node config-manager.js --reset

配置写在 ~/.tts-config.json，覆盖 voice、language、format、pitch、rate、volume 六项。

语速取值参考官方给出的区间：

"default" : Normal speed
"-20%" to "-10%" : Slow, clear (tutorials, stories, accessibility)
"+10%" to "+20%" : Slightly fast (summaries)
"+30%" to "+50%" : Fast (news, efficiency)

生成带字幕的版本，加 --save-subtitles，字幕为 JSON 格式，含词级时间轴。

适用场景与注意¶

适合这几类情况：

1、Agent 已经产出了一段内容，需要念出来而不是让用户读——多任务、无障碍、驾驶、烹饪等场景。
2、需要指定音色、语速、音调或音频格式。
3、需要字幕，用于后续对齐或检索。

限制和坑：

1、依赖联网。node-edge-tts 走的是在线服务，离线环境用不了。
2、默认输出是 MP3，不是 WAV 或ogg。
3、临时文件不自动清理。默认落到系统临时目录（Unix 是 /tmp/edge-tts-temp/，Windows 是 C:\Users\<user>\AppData\Local\Temp\edge-tts-temp\），文件名带随机后缀。上游文档明确写了：调用方需要自己处理清理，需要长期保存就指定 --output。
4、请求超时默认 10000ms，文本很长或网络较慢时可能要调 --timeout。
5、默认音色是 en-US-MichelleNeural，但 --voice 的默认值是 en-US-AriaNeural，两者不同，写脚本时以显式指定为准。
6、Windows 上注意路径分隔符和临时目录差异。

自检：

cd scripts
npm test

会生成 test-output.mp3 并验证服务可用。音色试听可以在 https://tts.travisvn.com/ 上换不同音色预览。

结尾¶

Edge TTS 的价值在于把”文本转语音”压缩成一条命令：不需要密钥，不需要自建服务，装完依赖就能在脚本里调。对需要让 Agent 输出语音、又不想为 TTS 单独搭一套工程的场景，它是够用的。技能地址：https://api.skillhub.cn/org-b6kzcl68/edge-tts ，上游仓库 https://clawhub.ai/i3130002/edge-tts 。