语音交互技能-feishu&qq-byLi

飞书语音交互技能。支持语音消息自动识别、AI 处理、语音回复全流程。需要配置 FEISHU_APP_ID 和 FEISHU_APP_SECRET 环境变量。使用 faster-whisper 进行语音识别，Edge TTS 进行语音合成，自动转换 OPUS 格式并通过飞书发送。适用于飞书平台的语音对话场景。

Security Scan

The skill largely does what it says (Feishu voice in→ASR→LLM→TTS→send), but there are notable mismatches and risky behaviors (metadata omission of required credentials, scripts that modify other extensions, and config-file access to other accounts) that you should review before installing or running in production.

Purpose & Capability

SKILL.md and multiple scripts clearly require FEISHU_APP_ID and FEISHU_APP_SECRET and describe reading openclaw.json; however the registry 'Requirements' block lists no required env vars or primary credential — that metadata omission is inconsistent. The repository contains many installer/scripts and a 'fix-debug-leak.sh' that modifies other OpenClaw extensions (/root/.openclaw/extensions/qqbot/), which is outside the narrow scope of simply handling Feishu audio and is a risky, cross-extension capability.

Instruction Scope

Runtime instructions and scripts do what the description claims (faster-whisper, edge-tts, ffmpeg conversion, send via Feishu). But they also: (1) read openclaw.json as a fallback (which can contain other channel credentials), (2) include a fix-debug-leak.sh script whose purpose is to edit other extensions' source files and clear caches, and (3) write logs and temporary audio to /tmp/openclaw — all described in SKILL.md. The cross-extension modification capability and config-file reading broaden the skill's scope beyond a single-channel audio handler.

Install Mechanism

There is no formal install spec in registry metadata (instruction-only), but the bundle includes install.sh and install-with-model-choice.sh which perform environment/venv setup and model downloads. Documentation and security notes indicate previous risks (curl | sh, eval) were fixed: scripts now download to temp files and verify shebang before executing. The skill defaults to a non-official HuggingFace mirror (https://hf-mirror.com) which is documented and configurable.

Credentials

FEISHU_APP_ID and FEISHU_APP_SECRET are required by the skill and appropriate for Feishu integration — however the registry metadata did not declare these required env vars, creating a metadata/information gap. Additionally the skill will read openclaw.json (multi-agent support) as a fallback and can access multiple Feishu account credentials if configured; that expands credential access beyond the single-app case and should be explicitly authorized by the operator.

Persistence & Privilege

always:false and autonomous invocation are normal. However the included 'fix-debug-leak.sh' and accompanying docs explicitly instruct modifying other extensions under /root/.openclaw/extensions/qqbot/ and clearing caches — this is a powerful, cross-extension operation that requires elevated trust and careful review. The skill also writes logs and temporary audio files to /tmp/openclaw; ensure you accept that storage/retention policy.

What to consider before installing

What to check before installing/using this skill: - Metadata vs docs: The SKILL.md and many scripts require FEISHU_APP_ID and FEISHU_APP_SECRET but the registry 'Requirements' block lists none — assume you must supply Feishu app credentials. Prefer environment variables (FEISHU_APP_ID/FEISHU_APP_SECRET) rather than openclaw.json. - Review scripts before running install: Although the package documents that previous risky patterns (curl|sh, eval) were fixed, manually inspect scripts/install.sh and install-with-model-choice.sh to confirm remote downloads are validated and there is no direct pipe-to-sh. If uncomfortable, run installation steps manually or use the venv+pip fallback. - Do not run fix-debug-leak.sh on production without review: This script modifies other OpenClaw extension code under /root/.openclaw/extensions/, which is an out-of-band operation. If you need the fix, first backup affected extensions and test in an isolated environment. - Credential scope: Multi-agent mode and reading openclaw.json can expose other accounts' app secrets. If you do not want that, remove the openclaw.json fallback or ensure only minimal credentials are present. Prefer setting OPENCLAW_ACCOUNT_ID and per-agent environment variables to limit scope. - Model mirror risk: The default HuggingFace mirror (https://hf-mirror.com) is non-official; switch HF_ENDPOINT to https://huggingface.co if you prefer the official source or use offline model files. - Log & tmp files: The skill writes logs and temporary audio to /tmp/openclaw/. Confirm retention/permissions and run the cleanup script or cron as desired. Check LOG_DIR/TEMP_DIR settings in .env. - Run in test environment first: Install and test in an isolated/test instance, validate Feishu messaging behavior, confirm no unexpected network destinations, and rotate credentials after initial deployment if you had to expose them during testing. If you want, I can: (a) point to the exact lines in install.sh/common.sh/feishu-tts.sh to verify there are no remaining 'curl|sh' or 'eval' patterns, or (b) produce a minimal checklist / command sequence to safely install and audit the skill in a sandbox.

Li Feishu Audio - 飞书语音交互技能

快速开始

本技能提供完整的飞书语音交互能力：

用户语音 → faster-whisper 识别 → AI 处理 → Edge TTS 合成 → OPUS 转换 → 飞书发送

日志管理

所有调试信息自动记录到日志文件，不会发送给用户

• 日志目录: /tmp/openclaw/
• 日志文件: 按日期自动创建（如 openclaw-2026-03-22.log）
• 自动清理: 每天凌晨 2 点清理旧文件，每周日凌晨 3 点清理 7 天前日志

详见：scripts/LOGGING.md

核心组件

1. 语音识别 (fast-whisper)

脚本: 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

2. 语音合成 (Edge TTS)

脚本: scripts/tts-voice.sh

用法:

./scripts/tts-voice.sh "文本内容" [输出文件.mp3]

配置:

• 音色：zh-CN-XiaoxiaoNeural (中文女声)
• 输出格式：MP3 (自动转换为 OPUS)
• 虚拟环境：技能目录下的 .venv（自动创建）

3. 飞书语音发送

脚本: scripts/feishu-tts.sh

用法:

./scripts/feishu-tts.sh <音频文件.mp3> [用户 ID]

配置:

• 飞书 AppID: 从环境变量或 openclaw.json 读取
• 音频格式：OPUS (48kHz, 自动转换)
• 消息类型：audio

4. 自动清理

脚本: scripts/cleanup-tts.sh

用法:

./scripts/cleanup-tts.sh [保留数量]

定时任务: 每天凌晨 2 点自动执行

完整工作流

接收用户语音消息

1. 飞书收到语音消息（OGG/OPUS 格式）
2. 保存到 OpenClaw 媒体目录（自动处理）
3. 调用 fast-whisper-fast.sh 识别

生成回复

1. 识别结果发送给大模型
2. 大模型生成文字回复
3. 调用 tts-voice.sh 生成语音

发送语音回复

1. TTS 生成 MP3 文件
2. sendMediaFeishu 自动转换为 OPUS
3. 通过飞书 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

故障排查

语音识别失败

问题: 无法识别语音内容

检查:

1. 模型是否下载：ls $FAST_WHISPER_MODEL_DIR/
2. 虚拟环境：技能目录/.venv/bin/python --version
3. 网络：export HF_ENDPOINT=https://hf-mirror.com

TTS 生成失败

问题: 无法生成语音文件

检查:

1. edge-tts 安装：uv pip list -p 技能目录/.venv | grep edge
2. 网络连接：Edge TTS 需要访问微软服务
3. 输出目录权限

飞书发送失败

问题: 语音消息发送失败

检查:

1. 凭证配置：echo $FEISHU_APP_ID
2. 音频格式：必须是 OPUS
3. 用户 ID 类型：使用 open_id

性能指标

操作	耗时
语音识别 (tiny)	~8-10 秒
TTS 生成	~3-5 秒
OPUS 转换	<1 秒
飞书上传	~2-3 秒
总计	~15 秒

最佳实践

语音质量

1. 录音环境: 安静环境，减少背景噪音
2. 说话速度: 正常语速，避免过快
3. 音频格式: 飞书自动发送 OPUS 格式

文件管理

1. 定期清理: 每天凌晨自动清理
2. 保留策略: 保留最近 10 个 TTS 目录
3. 空间上限: 100MB 自动清理

错误处理

1. 识别误差: 允许用户文字补充
2. 发送失败: 降级为文字回复
3. 超时处理: 设置合理超时时间

扩展功能

添加新音色

编辑 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
• 作者: 北京老李 (BeijingLL)
• faster-whisper: 1.2.1
• edge-tts: 7.2.7
• Python: 3.11

安全与供应链

必需的凭证

变量名	必需	说明
FEISHU_APP_ID	✅	飞书应用 ID (cli_xxx)
FEISHU_APP_SECRET	✅	飞书应用密钥
FAST_WHISPER_MODEL_DIR	❌	模型目录，默认 ~/.fast-whisper-models
VENV_DIR	❌	虚拟环境目录，默认技能目录下 .venv
TEMP_DIR	❌	临时文件目录，默认 /tmp
OPENCLAW_CONFIG	❌	OpenClaw 配置路径
LOG_DIR	❌	日志目录，默认技能目录下 logs

外部依赖说明

HuggingFace 镜像: 默认使用 https://hf-mirror.com 加速国内下载，可通过环境变量 HF_ENDPOINT 修改。

uv 安装: install.sh 会在未安装 uv 时提示安装命令。建议从官方源验证后再执行。

Microsoft Edge TTS: TTS 服务调用微软 Azure 语音服务，需要网络访问。

安全说明

凭证管理

• ✅ 使用环境变量存储敏感凭证
• ✅ 不要将 .env 提交到版本控制
• ✅ 将 .env 加入 .gitignore

路径配置

• ✅ 使用可配置的路径（环境变量）
• ✅ 避免硬编码个人路径
• ✅ 使用相对路径或系统级目录

临时文件

• ✅ 定期清理临时文件
• ✅ 使用系统临时目录 /tmp/
• ✅ 设置合理的保留策略

---

⚠️ 安全注意事项

1. 修复脚本风险

⚠️ 注意: fix-debug-leak.sh 脚本会修改其他 OpenClaw 扩展的源码。

• 此脚本用于修复飞书/Q4Bot 的调试信息泄露问题
• 会修改 /root/.openclaw/extensions/qqbot/ 等扩展
• 建议: 仅在确认需要时使用，并在测试环境验证

2. 模型镜像

默认使用 https://hf-mirror.com 镜像下载模型。

• 如需使用官方镜像，在 .env 中设置：

export HF_ENDPOINT=https://huggingface.co

3. 凭证安全

• 优先使用环境变量设置凭证
• 读取 openclaw.json 时可能接触其他账户凭证
• 多 Agent 模式下会自动读取对应账户配置

4. 生产环境建议

• ✅ 在测试环境先验证
• ✅ 仔细审查所有脚本
• ✅ 使用环境变量存储凭证
• ✅ 定期更新依赖