Li Feishu Audio - 飞书语音交互技能
快速开始
本技能提供完整的飞书语音交互能力：
用户语音 → faster-whisper 识别 → AI 处理 → Edge TTS 合成 → OPUS 转换 → 飞书发送
日志管理
所有调试信息自动记录到日志文件，不会发送给用户
日志目录: /tmp/openclaw/
日志文件: 按日期自动创建（如 openclaw-2026-03-22.log）
自动清理: 每天凌晨 2 点清理旧文件，每周日凌晨 3 点清理 7 天前日志
详见：scripts/LOGGING.md
核心组件
脚本: scripts/fast-whisper-fast.sh
用法: ./scripts/fast-whisper-fast.sh <音频文件.ogg>
配置:
模型：faster-whisper tiny/base/small/medium（可配置）
语言：中文 (zh)
模型目录：可配置（环境变量 FAST_WHISPER_MODEL_DIR）
虚拟环境：技能目录下的 .venv（自动创建）
模型选择:
# 安装时选择模型
./scripts/install-with-model-choice.sh
# 或编辑 .env 文件
WHISPER_MODEL=base # tiny/base/small/medium
详见：scripts/MODEL_CHOICE.md
脚本: scripts/tts-voice.sh
用法: ./scripts/tts-voice.sh "文本内容" [输出文件.mp3]
配置:
音色：zh-CN-XiaoxiaoNeural (中文女声)
输出格式：MP3 (自动转换为 OPUS)
虚拟环境：技能目录下的 .venv（自动创建）
脚本: scripts/feishu-tts.sh
用法: ./scripts/feishu-tts.sh <音频文件.mp3> [用户 ID]
配置:
飞书 AppID: 从环境变量或 openclaw.json 读取
音频格式：OPUS (48kHz, 自动转换)
消息类型：audio
脚本: scripts/cleanup-tts.sh
用法: ./scripts/cleanup-tts.sh [保留数量]
定时任务: 每天凌晨 2 点自动执行
完整工作流
接收用户语音消息
飞书收到语音消息（OGG/OPUS 格式）
保存到 OpenClaw 媒体目录（自动处理）
调用 fast-whisper-fast.sh 识别
生成回复
识别结果发送给大模型
大模型生成文字回复
调用 tts-voice.sh 生成语音
发送语音回复
TTS 生成 MP3 文件
sendMediaFeishu 自动转换为 OPUS
通过飞书 API 发送语音消息
环境要求
系统依赖
# Python
Python 3.11+
uv 包管理器
# 音频处理
ffmpeg (支持 OPUS 编码)
jq (JSON 处理)
# 飞书 API
飞书开放平台应用凭证
Python 环境
# 虚拟环境
技能目录/.venv （自动创建）
# 已安装包
faster-whisper==1.2.1
edge-tts==7.2.7
模型文件
# 语音识别模型
$FAST_WHISPER_MODEL_DIR/models--Systran--faster-whisper-tiny/
配置说明
飞书凭证
方法 1: 环境变量（推荐）
创建 .env 文件：
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
方法 2: openclaw.json
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxx",
"appSecret": "xxx"
}
}
}
⚠️ 安全提示：不要将凭证提交到版本控制系统！
自定义目录（可选）
在 .env 文件中配置：
# 模型目录（默认：$HOME/.fast-whisper-models）
export FAST_WHISPER_MODEL_DIR="/opt/fast-whisper-models"
# 虚拟环境目录（默认：技能目录/.venv）
export VENV_DIR="/path/to/venv"
# 临时文件目录（默认：/tmp）
export TEMP_DIR="/tmp"
# 日志目录（默认：技能目录/logs）
export LOG_DIR="/path/to/logs"
# OpenClaw 配置路径（默认：$HOME/.openclaw/openclaw.json）
export OPENCLAW_CONFIG="$HOME/.openclaw/openclaw.json"
TTS 配置
{
"messages": {
"tts": {
"auto": "always",
"provider": "edge",
"edge": {
"enabled": true,
"voice": "zh-CN-XiaoxiaoNeural",
"lang": "zh-CN"
}
}
}
}
脚本说明
fast-whisper-fast.sh
#!/bin/bash
# 语音识别脚本
export HF_ENDPOINT=https://hf-mirror.com
# 国内镜像
VENV_PYTHON="技能目录/.venv/bin/python"
# 由 install.sh 自动配置
# 用法
./fast-whisper-fast.sh <音频文件>
输出格式: [0.00s -> 2.32s] 识别的文本内容
tts-voice.sh
#!/bin/bash
# TTS 语音生成脚本
export HF_ENDPOINT=https://hf-mirror.com
VENV_PYTHON="技能目录/.venv/bin/python"
# 用法
./tts-voice.sh "文本内容" [输出文件.mp3]
feishu-tts.sh
#!/bin/bash
# 飞书语音发送脚本
# 自动转换 MP3 → OPUS
# 用法
./feishu-tts.sh <音频文件.mp3> [用户 ID]
转换参数:
ffmpeg -y -i input.mp3 -acodec libopus -ar 48000 -ac 1 output.opus
cleanup-tts.sh
#!/bin/bash
# TTS 临时文件清理脚本
# 用法
./cleanup-tts.sh [保留数量]
# 默认保留 10 个
# 定时任务（crontab）
0 2
* ./cleanup-tts.sh 10
故障排查
语音识别失败
问题: 无法识别语音内容
检查:
模型是否下载：ls $FAST_WHISPER_MODEL_DIR/
虚拟环境：技能目录/.venv/bin/python --version
网络：export HF_ENDPOINT=https://hf-mirror.com
TTS 生成失败
问题: 无法生成语音文件
检查:
edge-tts 安装：uv pip list -p 技能目录/.venv | grep edge
网络连接：Edge TTS 需要访问微软服务
输出目录权限
飞书发送失败
问题: 语音消息发送失败
检查:
凭证配置：echo $FEISHU_APP_ID
音频格式：必须是 OPUS
用户 ID 类型：使用 open_id
性能指标
操作 耗时
语音识别 (tiny) ~8-10 秒
TTS 生成 ~3-5 秒
OPUS 转换 <1 秒
飞书上传 ~2-3 秒
总计 ~15 秒
最佳实践
语音质量
录音环境: 安静环境，减少背景噪音
说话速度: 正常语速，避免过快
音频格式: 飞书自动发送 OPUS 格式
文件管理
定期清理: 每天凌晨自动清理
保留策略: 保留最近 10 个
TTS 目录
空间上限: 100MB
自动清理
错误处理
识别误差: 允许用户文字补充
发送失败: 降级为文字回复
超时处理: 设置合理超时时间
扩展功能
添加新音色
编辑 tts-voice.sh:
# 中文男声
communicate = edge_tts.Communicate(TEXT, "zh-CN-YunxiNeural")
# 英文女声
communicate = edge_tts.Communicate(TEXT, "en-US-MichelleNeural")
调整语速音调
# 在 edge_tts 中调整
communicate = edge_tts.Communicate(
TEXT,
"zh-CN-XiaoxiaoNeural",
rate="+10%",
# 语速
pitch="-5%"
# 音调
)
支持更多语言
修改 fast-whisper-fast.sh:
# 多语言识别
model.transcribe("$AUDIO_FILE", language="auto")
相关文件
配置: .env 文件或 openclaw.json
脚本: 技能目录下的 scripts/
模型: 可配置（FAST_WHISPER_MODEL_DIR，默认 $HOME/.fast-whisper-models）
临时文件: 可配置（TEMP_DIR，默认 /tmp）
虚拟环境: 可配置（VENV_DIR，默认 技能目录/.venv）
日志: 可配置（LOG_DIR，默认 技能目录/logs）
版本信息
技能版本: 0.1.3.1
by