OpenClaw 飞书语音聊天 - 完全离线版#

Python License

一个为 OpenClaw + 飞书客户端设计的全语音对话技能，基于 Qwen3-TTS 和 Whisper 实现完全离线的语音识别和语音合成。无需任何云端 API，所有模型本地运行。

✨ 特性#

• 🎤 完全离线运行 - 所有模型本地运行，不需要云端 API，保护隐私
• 🚀 高性能 - 使用常驻内存的 HTTP 服务，模型只加载一次，响应速度快
• 🎯 自动触发 - 收到语音消息自动识别，回复自动合成语音，无需手动操作
• 🌍 多语言支持 - 支持中文、英文、日语、韩语等 10 种语言的识别和合成
• 🎨 音色克隆 - 支持自定义音色嵌入，可将任意人声克隆为参考音色文件
• 🔌 OpenAI 兼容 - TTS 服务兼容 OpenAI TTS API，可直接集成到 OpenClaw
• 🔧 易于部署 - 一键安装脚本，自动配置虚拟环境
• 🛠️ 音色克隆工具 - 提供独立工具用于音色克隆和测试
• 🧹 智能文本清理 - 自动清理 LLM 回复中的括号描述和表情符号，只朗读实际内容

📋 目录#

• 快速开始
• 项目结构
• 安装
• 配置
• 使用方法
• 工作原理
• 依赖要求
• 常见问题
• 贡献
• 许可证

🚀 快速开始#

1. 克隆项目#

bash

git clone https://github.com/shuaishi1991/openclaw-feishu-voice-free.git
cd openclaw-feishu-voice-free

2. 安装和部署#

按照 安装 部分的详细步骤进行：

1. 复制文件到 OpenClaw skills 目录
2. 运行安装脚本（ bash setup.sh）
3. 下载模型文件（Whisper 和 Qwen3-TTS）

3. 配置 OpenClaw#

编辑 /root/.openclaw/openclaw.json，按照 配置 部分的说明添加配置。

4. 启动服务#

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

# 启动 Whisper ASR 服务（端口 8001）
nohup python scripts/server/whisper-server.py --port 8001 > /tmp/whisper-server.log 2>&1 &

# 启动 Qwen3-TTS 服务（端口 8000，使用 OpenAI 兼容 API）
nohup python scripts/server/tts-base-server-openai.py --port 8000 --clone voice_embedings/huopo_kexin.pt > /tmp/tts-server.log 2>&1 &

deactivate

注意： 如果还没有音色文件，可以先不指定 --clone 参数，使用默认音色。后续可以通过 音色克隆工具 创建自定义音色。

5. 重启 OpenClaw#

bash

openclaw gateway restart

现在你可以在飞书发送语音消息，系统会自动识别并回复语音！

---

详细说明： 如需了解更多信息，请查看 安装、 配置 和 使用方法 部分。

📁 项目结构#

text

openclaw-feishu-voice-free/
├── README.md                          # 项目说明文档
├── setup.sh                           # 虚拟环境安装脚本
├── openclaw.json                      # 配置文件示例
├── voice_embedings/                   # 存放克隆好的音色文件（.pt 格式）
└── scripts/
    ├── server/
    │   ├── whisper-server.py          # Whisper ASR HTTP 服务（端口 8001）
    │   ├── tts-base-server.py         # Qwen3-TTS HTTP 服务（自定义 API）
    │   └── tts-base-server-openai.py   # Qwen3-TTS HTTP 服务（OpenAI 兼容 API，推荐）
    └── tools/
        └── tts-base.py                 # 音色克隆工具（独立测试和克隆音色）

📦 安装#

系统要求#

• Python 3.10 - 3.12
• OpenClaw 已安装并运行
• 足够的磁盘空间（模型文件约 5-10GB）
• GPU 推荐（CPU 也可运行，但速度较慢）
• 网络连接（用于下载模型，首次使用需要）

模型要求#

需要下载以下模型到本地：

模型HuggingFace Repo默认路径大小Whisper ASRopenai/whisper-large-v3-turbo``/root/.openclaw/models/whisper/whisper-large-v3-turbo~3GBQwen3-TTSQwen/Qwen3-TTS-12Hz-1.7B-Base``/root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base~3.5GB

安装步骤#

1. 复制文件到 OpenClaw skills 目录

bash

mkdir -p /root/.openclaw/skills/openclaw-feishu-voice-free
cp -r * /root/.openclaw/skills/openclaw-feishu-voice-free/
chmod +x /root/.openclaw/skills/openclaw-feishu-voice-free/setup.sh

1. 运行安装脚本

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
bash setup.sh

setup.sh 会自动：

• 检测 Python 版本
• 创建虚拟环境
• 安装所有必需的依赖包

1. 下载模型文件

需要下载两个模型到本地：

下载 Whisper 模型（ASR）

bash

# 创建模型目录
mkdir -p /root/.openclaw/models/whisper

# 使用 huggingface-cli 下载（推荐）
pip install huggingface_hub
huggingface-cli download openai/whisper-large-v3-turbo \
  --local-dir /root/.openclaw/models/whisper/whisper-large-v3-turbo \
  --local-dir-use-symlinks False

# 或者使用 Python 脚本下载
python -c "
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='openai/whisper-large-v3-turbo',
    local_dir='/root/.openclaw/models/whisper/whisper-large-v3-turbo',
    local_dir_use_symlinks=False
)
"

下载 Qwen3-TTS 模型（TTS）

bash

# 创建模型目录
mkdir -p /root/.openclaw/models/Qwen3-TTS

# 使用 huggingface-cli 下载（推荐）
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base \
  --local-dir /root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base \
  --local-dir-use-symlinks False

# 或者使用 Python 脚本下载
python -c "
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='Qwen/Qwen3-TTS-12Hz-1.7B-Base',
    local_dir='/root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base',
    local_dir_use_symlinks=False
)
"

注意：

• 模型文件较大（约 5-10GB），下载需要一些时间
• 确保有足够的磁盘空间
• 如果网络较慢，可以使用镜像站点或手动下载

1. 安装系统依赖（可选）

bash

# Ubuntu/Debian
apt install ffmpeg

# CentOS/RHEL
yum install ffmpeg

⚙️ 配置#

OpenClaw 配置#

在 /root/.openclaw/openclaw.json 中配置：

1. 配置 Whisper ASR（语音识别）

在 tools.media.audio 中配置 Whisper 服务：

json

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          {
            "type": "cli",
            "command": "bash",
            "args": [
              "-c",
              "curl -s -X POST http://localhost:8001/transcribe -H 'Content-Type: application/json' -d \"{\\\"audio_path\\\": \\\"{{MediaPath}}\\\", \\\"language\\\": \\\"Chinese\\\"}\" | jq -r '.text // empty'"
            ],
            "timeoutSeconds": 60
          }
        ]
      }
    }
  }
}

2. 配置 Qwen3-TTS（语音合成）

在 messages.tts 中配置 TTS 服务（使用 OpenAI 兼容 API）：

json

{
  "messages": {
    "tts": {
      "auto": "always",
      "provider": "openai",
      "timeoutMs": 120000,
      "openai": {
        "apiKey": "no need",
        "baseUrl": "http://localhost:8000/v1",
        "model": "Qwen3-TTS-12Hz-1.7B-Base",
        "voice": "huopo_kexin"
      }
    }
  }
}

注意：

• baseUrl 指向本地 TTS 服务（使用 tts-base-server-openai.py）
• voice 参数会被忽略（实际使用启动服务时指定的 --clone 音色文件）
• apiKey 可以设置为任意值（本地服务不需要）

服务配置#

Whisper ASR 服务

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

python scripts/server/whisper-server.py \
  --port 8001 \
  --model /root/.openclaw/models/whisper/whisper-large-v3-turbo \
  --language Chinese

参数说明：

• --port: 服务端口（默认 8001）
• --model: 模型路径或 HuggingFace repo ID（默认 openai/whisper-large-v3-turbo）
• --language: 默认识别语言（默认 Chinese）
• --batch-size: 批处理大小（默认 16）

模型说明：

• 默认使用 openai/whisper-large-v3-turbo 模型
• 也可以使用其他 Whisper 模型，如 openai/whisper-large-v3、 openai/whisper-medium 等
• 如果模型已下载到本地，直接使用本地路径
• 如果使用 HuggingFace repo ID，首次运行时会自动下载

Qwen3-TTS 服务（推荐：OpenAI 兼容 API）

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

python scripts/server/tts-base-server-openai.py \
  --port 8000 \
  --model /root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base \
  --clone voice_embedings/huopo_kexin.pt

参数说明：

• --port: 服务端口（默认 8000）
• --model: 模型路径或 HuggingFace repo ID（默认 Qwen/Qwen3-TTS-12Hz-1.7B-Base）
• --clone: 音色克隆文件路径（可选，支持相对路径）

音色文件路径：

• 支持绝对路径： /path/to/voice.pt
• 支持相对路径： voice_embedings/my_voice.pt（会自动在 skill 目录和 voice_embedings 目录查找）
• 如果不指定，使用默认音色

API 端点：

• POST /v1/audio/speech - 生成语音（兼容 OpenAI TTS API）
• GET /v1/models - 获取模型列表
• GET / - 健康检查

Qwen3-TTS 服务（自定义 API，可选）

如果需要使用自定义 API 格式，可以使用 tts-base-server.py：

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

python scripts/server/tts-base-server.py \
  --port 8000 \
  --model /root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base \
  --clone voice_embedings/my_voice.pt

API 端点：

• POST /generate - 生成语音
• GET / - 健康检查

🎯 使用方法#

音色克隆#

使用 scripts/tools/tts-base.py 工具可以克隆任意人声并生成音色文件：

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

# 从参考音频克隆音色并保存为 .pt 文件
python scripts/tools/tts-base.py \
  --audio /path/to/reference_audio.wav \
  --text "这是参考音频的文字内容" \
  --save-clone voice_embedings/my_custom_voice.pt \
  --prompt "测试生成的语音"

# 使用已保存的音色文件生成语音
python scripts/tools/tts-base.py \
  --clone voice_embedings/my_custom_voice.pt \
  --prompt "使用克隆音色生成的文本" \
  --output output.wav

deactivate

音色克隆说明：

• --audio: 参考音频文件路径（支持 wav、mp3、m4a 格式）
• --text: 参考音频的文字内容（必须准确）
• --save-clone: 保存克隆音色到指定路径（.pt 格式）
• --clone: 使用已保存的音色文件生成语音
• 生成的音色文件保存在 voice_embedings/ 目录下

基本使用#

1. 启动服务（在 venv 中）

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

# 启动 Whisper ASR 服务（端口 8001）
nohup python scripts/server/whisper-server.py --port 8001 > /tmp/whisper-server.log 2>&1 &

# 启动 Qwen3-TTS 服务（端口 8000，OpenAI 兼容 API）
nohup python scripts/server/tts-base-server-openai.py --port 8000 --clone voice_embedings/huopo_kexin.pt > /tmp/tts-server.log 2>&1 &

deactivate

1. 检查服务状态

bash

# 检查 Whisper 服务
curl http://localhost:8001/

# 检查 TTS 服务
curl http://localhost:8000/

1. 重启 OpenClaw

bash

openclaw gateway restart

1. 在飞书发送语音消息

系统会自动：

• 识别语音为文字（通过 Whisper 服务）
• 调用 LLM 生成回复
• 合成语音回复（通过 Qwen3-TTS 服务）
• 发送语音消息给用户

手动测试#

测试 ASR（语音转文字）

bash

# 使用 curl 测试 Whisper 服务
curl -X POST http://localhost:8001/transcribe \
  -H "Content-Type: application/json" \
  -d '{"audio_path": "/path/to/audio.mp3", "language": "Chinese"}'

测试 TTS（文字转语音）

bash

# 使用 curl 测试 TTS 服务（OpenAI 兼容 API）
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-TTS-12Hz-1.7B-Base",
    "input": "你好，欢迎使用 Qwen3-TTS",
    "voice": "alloy"
  }' \
  --output output.mp3

使用 systemd 管理服务（推荐生产环境）#

创建 systemd 服务文件可以确保服务在系统重启后自动启动：

创建 Whisper ASR 服务

创建 /etc/systemd/system/openclaw-feishu-voice-free-whisper.service：

ini

[Unit]
Description=OpenClaw Feishu Voice Free Whisper ASR Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/.openclaw/skills/openclaw-feishu-voice-free
Environment="PATH=/root/.openclaw/skills/openclaw-feishu-voice-free/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/root/.openclaw/skills/openclaw-feishu-voice-free/venv/bin/python scripts/server/whisper-server.py --port 8001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

创建 Qwen3-TTS 服务

创建 /etc/systemd/system/openclaw-feishu-voice-free-tts.service：

ini

[Unit]
Description=OpenClaw Feishu Voice Free Qwen3-TTS Server (OpenAI Compatible)
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/.openclaw/skills/openclaw-feishu-voice-free
Environment="PATH=/root/.openclaw/skills/openclaw-feishu-voice-free/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/root/.openclaw/skills/openclaw-feishu-voice-free/venv/bin/python scripts/server/tts-base-server-openai.py --port 8000 --clone voice_embedings/huopo_kexin.pt
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动服务

bash

sudo systemctl daemon-reload
sudo systemctl enable openclaw-feishu-voice-free-whisper openclaw-feishu-voice-free-tts
sudo systemctl start openclaw-feishu-voice-free-whisper openclaw-feishu-voice-free-tts
sudo systemctl status openclaw-feishu-voice-free-whisper openclaw-feishu-voice-free-tts

🔧 工作原理#

工作流程#

text

1. 用户在飞书发送语音消息
   ↓
2. OpenClaw 接收并下载音频文件到本地
   ↓
3. OpenClaw 通过 tools.media.audio 配置调用 Whisper 服务（HTTP API）
   POST http://localhost:8001/transcribe
   ↓
4. Whisper 服务识别语音为文字，返回给 OpenClaw
   ↓
5. OpenClaw 调用 LLM（如 GPT、Claude 等）生成文字回复
   ↓
6. OpenClaw 通过 messages.tts 配置调用 TTS 服务（OpenAI 兼容 API）
   POST http://localhost:8000/v1/audio/speech
   ↓
7. TTS 服务合成语音（自动清理括号内容和表情符号），返回 MP3 文件
   ↓
8. OpenClaw 发送语音消息给飞书用户

架构设计#

• OpenClaw: 负责消息接收、LLM 调用、文件 IO、与飞书客户端通信
• whisper-server: 常驻内存的 Whisper 模型，提供 ASR 服务（HTTP API）
• tts-base-server-openai: 常驻内存的 Qwen3-TTS 模型，提供 TTS 服务（兼容 OpenAI API）
• 飞书客户端: 用户发送语音消息，接收语音回复

文本清理#

TTS 服务会自动清理 LLM 回复中的括号描述内容和表情符号，不会朗读：

text

输入: "(嘴角微笑) 今天天气真好😊 (看向窗外)"
输出: "今天天气真好"

清理规则：

• 移除所有圆括号内容： (xxx)
• 移除所有方括号内容： [xxx]
• 移除所有花括号内容： {xxx}
• 移除所有表情符号（Emoji）
• 清理多余空格和换行

📋 依赖要求#

Python 依赖#

• torch - PyTorch 深度学习框架
• transformers - HuggingFace transformers（用于 Whisper）
• accelerate - 模型加速
• soundfile - 音频文件处理
• requests - HTTP 请求
• qwen-tts - Qwen3-TTS 模型
• pydub - 音频格式转换

所有依赖会在运行 setup.sh 时自动安装。

系统依赖#

• ffmpeg - 音频处理（可选，推荐安装）

❓ 常见问题#

Q: setup.sh 失败，提示 Python 版本不兼容#

A: 确保系统有 Python 3.10-3.12。检查版本：

bash

python3 --version

如果不是 3.10-3.12，需要安装正确版本。

Q: 服务启动失败#

A: 检查以下几点：

1. 端口是否被占用

bash

netstat -tulpn | grep -E "(8000|8001)"

1. 依赖是否安装

bash

source venv/bin/activate
pip list | grep -E "(torch|transformers|qwen-tts)"

1. 查看服务日志

bash

tail -f /tmp/whisper-server.log
tail -f /tmp/tts-server.log

Q: Skill 不触发#

A: 检查配置和日志：

1. 检查配置

bash

cat /root/.openclaw/openclaw.json | grep -A 20 "openclaw-feishu-voice-free"

1. 检查 skill 是否加载

bash

openclaw skill list | grep openclaw-feishu-voice-free

1. 查看 OpenClaw 日志

bash

tail -f /root/.openclaw/logs/openclaw.log

Q: TTS 不工作#

A: 确保：

1. messages.tts.auto: "always" 已设置
2. messages.tts.provider: "openai" 已设置（使用 OpenAI 兼容 API）
3. messages.tts.openai.baseUrl: "http://localhost:8000/v1" 已设置
4. TTS 服务在运行（端口 8000）
5. 检查服务健康状态： curl http://localhost:8000/
6. 检查服务日志： tail -f /tmp/tts-server.log

Q: 如何更换音色？#

A: 有两种方式：

方式1：使用音色克隆工具创建音色文件

bash

cd /root/.openclaw/skills/openclaw-feishu-voice-free
source venv/bin/activate

# 从参考音频克隆音色并保存
python scripts/tools/tts-base.py \
  --audio /path/to/reference_audio.wav \
  --text "参考音频的文字内容" \
  --save-clone voice_embedings/my_voice.pt \
  --prompt "测试文本"

deactivate

方式2：在启动服务时指定音色文件

bash

# 使用绝对路径
python scripts/server/tts-base-server-openai.py --clone /path/to/your-voice.pt

# 或使用相对路径（从 skill 目录或 voice_embedings 目录）
python scripts/server/tts-base-server-openai.py --clone voice_embedings/my_voice.pt

注意：

• 音色文件需要是 .pt 格式，使用 scripts/tools/tts-base.py 的 --save-clone 参数生成
• 修改音色后需要重启 TTS 服务才能生效
• 如果使用 systemd 管理服务，需要修改服务文件中的 --clone 参数

Q: 服务无法连接#

A: 检查以下几点：

1. 检查服务是否运行

bash

# 检查端口占用
netstat -tulpn | grep -E "(8000|8001)"

# 检查进程
ps aux | grep -E "(whisper-server|tts-base-server)"

1. 检查服务日志

bash

tail -f /tmp/whisper-server.log
tail -f /tmp/tts-server.log

1. 检查防火墙

bash

# 如果服务绑定在 0.0.0.0，确保防火墙允许端口
# Ubuntu/Debian
ufw allow 8000
ufw allow 8001

1. 检查模型文件

bash

# 检查 Whisper 模型
ls -lh /root/.openclaw/models/whisper/whisper-large-v3-turbo/

# 检查 Qwen3-TTS 模型
ls -lh /root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base/

Q: 音色文件找不到#

A: 检查以下几点：

1. 检查音色文件路径

bash

# 检查 voice_embedings 目录
ls -la /root/.openclaw/skills/openclaw-feishu-voice-free/voice_embedings/

1. 使用绝对路径

如果相对路径不工作，使用绝对路径：

bash

python scripts/server/tts-base-server-openai.py --clone /root/.openclaw/skills/openclaw-feishu-voice-free/voice_embedings/huopo_kexin.pt

1. 检查文件格式

确保音色文件是 .pt 格式，并且是通过 tts-base.py --save-clone 生成的

📄 许可证#

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

👤 作者#

Shuai Shi

• 项目主页: https://github.com/shuaishi1991/openclaw-feishu-voice-free

🙏 致谢#

• OpenClaw - 强大的 AI 助手框架
• Qwen3-TTS - 高质量的语音合成模型
• Whisper - 优秀的语音识别模型

⭐ Star History#

如果这个项目对你有帮助，请给个 Star ⭐！

---

注意: 这是一个 OpenClaw Skill，需要先安装和配置 OpenClaw 才能使用。