openclaw-feishu-voice-free

OpenClaw 飞书语音聊天技能，基于本地 Qwen3-TTS 和 Whisper，实现离线多语言语音识别与合成，无需云端API。

Security Scan

The skill mostly matches its stated offline ASR/TTS purpose, but there are several inconsistencies and sensitive items (embedded credentials in the shipped openclaw.json, explicit remote-mode upload in the cloning tool, and instructions that expose network services) that warrant caution before installation.

Purpose & Capability

The package implements local Whisper ASR and Qwen3-TTS servers and an installation script which is coherent with the described offline voice skill. However the bundle includes an openclaw.json containing Feishu appId/appSecret entries and a gateway token, which are unrelated to delivering local TTS/ASR functionality and unnecessary for the skill itself. Shipping sample/real channel credentials inside the skill is unexpected and potentially dangerous.

Instruction Scope

SKILL.md directs copying files into OpenClaw, running setup.sh, adding entries to /root/.openclaw/openclaw.json, starting long‑running HTTP servers, and optionally creating systemd services. The codebase is largely offline-capable, but the tts-base.py tool explicitly supports a --remote mode (and posts base64-encoded reference audio to arbitrary URLs), which contradicts the 'completely offline' claim and creates a possible exfiltration vector. The servers bind to 0.0.0.0 by default (exposing services network-wide) unless the operator restricts it.

Install Mechanism

There is no platform install spec, but setup.sh will create a venv and pip-install dependencies (torch, qwen-tts, transformers, pydub, etc.). This is expected for model-serving code; it is moderate risk (pip installs run arbitrary code) but not unusual for this type of skill. No downloads from obscure URLs are performed by the script itself (model downloads are delegated to huggingface-cli or snapshot_download).

Credentials

The skill declares no required env vars, yet code and docs reference environment variables (e.g., QWEN_TTS_REMOTE, QWEN_TTS_LANGUAGE) and the distributed openclaw.json contains what look like real credentials and a gateway token for Feishu and OpenClaw. Those credentials are not justified by the skill's purpose and could allow unauthorized access if they are active credentials or if the file is copied into a global config. The skill also instructs editing /root/.openclaw/openclaw.json — risk of accidentally overwriting or merging secrets.

Persistence & Privilege

The skill does not request 'always: true' and is user-invocable only. However the README and SKILL.md encourage creating systemd services to run the servers as root and restarting the OpenClaw gateway, which gives persistent network-exposed processes. Combined with the embedded gateway token and channel credentials, this increases the operational blast radius if those items are active or misused.

What to consider before installing

Do not blindly copy or overwrite system OpenClaw config files or use the provided openclaw.json without review—it contains Feishu appId/appSecret values and a gateway token. Treat those as sensitive: remove or replace them with your own credentials. If you want strictly offline operation, avoid using the --remote option in scripts/tools/tts-base.py and ensure QWEN_TTS_REMOTE is unset. When starting the servers, prefer binding to localhost (127.0.0.1) rather than 0.0.0.0 to avoid exposing endpoints to the network, and run services under a non-root account. Review setup.sh and pip requirements before running (pip installs execute code). Only download models from official sources you trust, and verify any embedded credentials are not active. If you’re unsure, run the skill in an isolated VM or container first and audit network traffic to confirm no unexpected outbound connections.

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

Python License

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

✨ 特性

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

📋 目录

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

🚀 快速开始

1. 克隆项目

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. 启动服务

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

openclaw gateway restart

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

---

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

📁 项目结构

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 ASR	openai/whisper-large-v3-turbo	/root/.openclaw/models/whisper/whisper-large-v3-turbo	~3GB
Qwen3-TTS	Qwen/Qwen3-TTS-12Hz-1.7B-Base	/root/.openclaw/models/Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base	~3.5GB

安装步骤

1. 复制文件到 OpenClaw skills 目录

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. 运行安装脚本

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

setup.sh 会自动：

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

1. 下载模型文件

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

下载 Whisper 模型（ASR）

# 创建模型目录
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）

# 创建模型目录
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. 安装系统依赖（可选）

# Ubuntu/Debian
apt install ffmpeg

# CentOS/RHEL
yum install ffmpeg

⚙️ 配置

OpenClaw 配置

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

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

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

{
  "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）：

{
  "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 服务

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）

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：

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 工具可以克隆任意人声并生成音色文件：

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 中）

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. 检查服务状态

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

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

1. 重启 OpenClaw

openclaw gateway restart

1. 在飞书发送语音消息

系统会自动：

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

手动测试

测试 ASR（语音转文字）

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

测试 TTS（文字转语音）

# 使用 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：

[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：

[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

启用并启动服务

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

🔧 工作原理

工作流程

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 回复中的括号描述内容和表情符号，不会朗读：

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

清理规则：

• 移除所有圆括号内容：(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。检查版本：

python3 --version

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

Q: 服务启动失败

A: 检查以下几点：

1. 端口是否被占用

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

1. 依赖是否安装

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

1. 查看服务日志

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

Q: Skill 不触发

A: 检查配置和日志：

1. 检查配置

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

1. 检查 skill 是否加载

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

1. 查看 OpenClaw 日志

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：使用音色克隆工具创建音色文件

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：在启动服务时指定音色文件

# 使用绝对路径
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. 检查服务是否运行

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

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

1. 检查服务日志

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

1. 检查防火墙

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

1. 检查模型文件

# 检查 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. 检查音色文件路径

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

1. 使用绝对路径

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

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 才能使用。