OpenSkillIndex← back to search
claude-codeopenclawautomation

Skills voice-tts

语音输入（Whisper ASR）+ 语音输出（Edge TTS）技能，支持 agent 专属音色，可调用 send_voice_reply.mjs 发送 Telegram 语音消息。

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/believe3344/voice-tts" ~/.claude/skills/openclaw-skills-voice-tts && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/believe3344/voice-tts" ~/.openclaw/skills/openclaw-skills-voice-tts && rm -rf "$T"
manifest: skills/believe3344/voice-tts/SKILL.md
tags
#asr#tts#voice#telegram#whisper#edgetts
source content

voice-tts

语音输入（ASR）+ 语音输出（TTS）技能，完整替代 OpenClaw 内置 tts 工具处理中文内容。

技术概览

方向技术说明
语音 → 文字Whisper（本地）接收语音，自动转文字
文字 → 语音Edge TTS（云端）生成 MP3，发送 Telegram 语音消息

工作方式

ASR（语音 → 文字）

用户发来语音消息 → 

voice-asr.mjs
转写为文字 → 触发 agent 处理。

语音识别在 OpenClaw 工具层自动完成，agent 收到的是文字。

TTS（文字 → 语音）

agent 回复文字后，如需以语音发送，调用 

send_voice_reply.mjs
手动发送 Telegram 语音消息：

node /path/to/voice-tts/scripts/send_voice_reply.mjs \
  --text "你的回复内容" \
  --chat-id 8317347201 \
  --agent main

快速安装

方式一：一键安装（推荐）

# 默认安装 turbo 模型
bash /path/to/voice-tts/install.sh

# 国内加代理
bash /path/to/voice-tts/install.sh --proxy http://127.0.0.1:7897

方式二：手动安装

pip install edge-tts whisper click
brew install ffmpeg   # macOS
sudo apt install -y ffmpeg  # Ubuntu

安装完成后运行冒烟测试：

bash tests/smoke.sh

配置（可选）

config.default.json
已包含所有默认值，不填配置可直接使用。

如需自定义 agent 音色映射或 ASR 参数，在 

openclaw.json
的 
skills.entries.voice-tts.config
中覆盖：

{
  "skills": {
    "entries": {
      "voice-tts": {
        "enabled": true,
        "config": {
          "tts": {
            "defaultVoice": "zh-CN-XiaoxiaoNeural",
            "agentVoices": {
              "main":       "zh-CN-XiaoxiaoNeural",
              "researcher": "zh-CN-YunxiNeural",
              "product":    "zh-CN-XiaoyiNeural",
              "coder":      "zh-CN-YunyangNeural",
              "devops":     "zh-CN-YunjianNeural"
            }
          },
          "asr": {
            "defaultInitialPrompt": "以下是中文语音转文字。常见词包括：管家、研究员、邮差、码农、产品、运维、OpenClaw、小爱、Telegram。",
            "defaultTemperature": 0,
            "conditionOnPreviousText": true
          }
        }
      }
    }
  }
}

修改后执行 

openclaw gateway restart
。

核心脚本

语音合成 — 
bin/voice-tts.mjs

将文字转为语音文件：

# 基本用法
node bin/voice-tts.mjs "你好" -f /tmp/demo.mp3

# 指定 agent 音色
node bin/voice-tts.mjs "你好" -f /tmp/demo.mp3 --agent main

# 指定声音 / 语速
node bin/voice-tts.mjs "你好" -f /tmp/demo.mp3 -v zh-CN-YunxiNeural -r +10%

可用中文音色：

zh-CN-XiaoxiaoNeural
（女声，推荐）、
zh-CN-YunxiNeural
、
zh-CN-XiaoyiNeural
、
zh-CN-YunyangNeural
、
zh-CN-YunjianNeural
、
zh-CN-XiaomoNeural

语音识别 — 
bin/voice-asr.mjs

将音频文件转文字：

# 基本用法
node bin/voice-asr.mjs audio.ogg

# 指定模型 / 语言
node bin/voice-asr.mjs audio.ogg --model turbo --language zh

# 输出 JSON（含语言检测）
node bin/voice-asr.mjs audio.ogg --json

可用模型：

tiny
base
small
turbo
large-v3

发送 Telegram 语音 — 
scripts/send_voice_reply.mjs

一键完成"文字 → TTS 合成 → Telegram 语音消息发送"：

node scripts/send_voice_reply.mjs \
  --text "已收到！" \
  --chat-id 8317347201 \
  --agent main

参数说明：

参数必填说明
--text
✅要语音播报的文字内容
--chat-id
✅Telegram 目标用户 ID
--agent
否agent id，自动选对应音色
--voice
否覆盖默认音色，如 
zh-CN-YunxiNeural
--rate
否语速，如 
+10%
、
-5%
--token
否直接指定 Telegram Bot Token

Token 自动查找优先级：

  1. --token
    参数
  2. openclaw.json → channels.telegram.accounts.<当前agent>.botToken
  3. openclaw.json → channels.telegram.accounts.default.botToken
  4. 环境变量 
    TELEGRAM_BOT_TOKEN

文件结构

voice-tts/
├── SKILL.md                      # 本文档
├── config.default.json           # 默认配置（直接可用，不需修改）
├── install.sh                    # 一键安装脚本
│
├── bin/
│   ├── voice-tts.mjs             # TTS 入口
│   └── voice-asr.mjs             # ASR 入口
│
├── lib/
│   ├── config.mjs                # 配置读取（支持 openclaw.json 覆盖）
│   ├── errors.mjs                 # 统一错误码 + 用户兜底消息
│   └── audio.mjs                 # 音频校验
│
├── scripts/
│   ├── send_voice_reply.mjs      # Telegram 语音发送（核心）
│   └── auto_voice_check          # 批量处理未处理语音
│
└── tests/
    └── smoke.sh                   # 冒烟测试

注意： 

scripts/edge_tts
和 
scripts/whisper
是内部 Python 封装，非直接入口；直接使用上表中的 
bin/
入口即可。

错误码

错误码含义用户兜底消息
no_file_path
未提供音频文件抱歉，没有收到音频文件，请重试。
file_not_found
文件不存在抱歉，音频文件没找到，请重试。
file_empty
文件为空抱歉，音频文件是空的，请重试。
file_too_small
文件过小抱歉，音频文件不完整，请重试。
file_stale
文件过期抱歉，音频文件已过期，请重试。
transcription_failed
Whisper 转写失败抱歉，语音识别失败了，请重试。
synthesis_failed
Edge TTS 生成失败抱歉，语音生成失败了，请重试。
timeout
执行超时抱歉，处理超时了，请稍后重试。

语音文件自动归档

voice-asr.mjs
成功转写后，自动将原文件从 
~/.openclaw/media/inbound/
复制到 agent workspace 
media/inbound/
，然后删除原文件。

  • ✅ 成功时：复制归档，删除原文件
  • ❌ 失败时：保留原文件，可重试

故障排查

# 检查依赖
ffmpeg -version
python3 -c "import edge_tts; print('edge-tts ok')"
python3 -c "import whisper; print('whisper ok')"

# 检查未处理语音文件
ls -la ~/.openclaw/media/inbound/

# 直接测试 ASR
node bin/voice-asr.mjs ~/.openclaw/media/inbound/your-file.ogg

# 直接测试 TTS
node bin/voice-tts.mjs "测试" -f /tmp/test.mp3

# 运行冒烟测试
bash tests/smoke.sh

常见问题：

  • TTS 生成失败：检查 
    python3 -c "import edge_tts; print('ok')"
  • Telegram 发送失败：确认 botToken 正确、chat-id 是数字 ID、语音文件 < 20MB
  • 语音发错对象：检查 
    conversationId
    是否与预期 chat-id 一致

可选：批量处理未处理语音

node scripts/auto_voice_check

检查 

~/.openclaw/media/inbound/
下未处理的 
.ogg
文件，自动转写并归档。