feishu voice reply

通过火山引擎 TTS 合成多音色语音，转换为 Opus 格式后，使用飞书 API 自动上传并发送语音消息。

Security Scan

The skill's functionality (Volcengine TTS → convert → Feishu upload/send) is coherent, but the package/metadata and SKILL.md/script contain inconsistencies and missing dependency declarations that you should review before installing.

Purpose & Capability

The skill's stated purpose (generate TTS with 火山引擎 and send via 飞书) matches the code: the script calls Volcengine and Feishu endpoints and converts with ffmpeg. However the registry metadata claims no required environment variables while SKILL.md and the script require VOLC_API_KEY, VOLC_RESOURCE_ID, FEISHU_APP_ID, and FEISHU_APP_SECRET—an important metadata mismatch that can mislead automated installers or reviewers. package.json also lists an npm dependency "ffmpeg": "*" which is not a real npm runtime dependency for a shell script and looks incorrect.

Instruction Scope

The SKILL.md instructions and the script stay within the declared purpose: they only call Volcengine and Feishu endpoints, convert audio with ffmpeg, and upload to Feishu. No unrelated system files or external endpoints are referenced. Concerns: (1) the bash script uses user-supplied TEXT directly inside JSON body without escaping — this can break requests or lead to malformed payloads if text contains quotes/newlines; (2) the script uses jq and ffmpeg but only ffmpeg is mentioned in SKILL.md (jq is not documented as required); (3) a likely bug in tmp filename (TMP_MP3="/tmp/voice-tts-$.mp3") may create unexpected filenames or collisions.

Install Mechanism

This is an instruction-only skill (no install spec) and therefore does not fetch or execute remote archives—low installation risk. The included files are a shell script and config templates. Minor oddity: package.json lists "ffmpeg" under dependencies which is inappropriate for a shell-based skill and could confuse some package managers.

Credentials

The environment variables required by the skill (VOLC_API_KEY, VOLC_RESOURCE_ID, FEISHU_APP_ID, FEISHU_APP_SECRET, optional FEISHU_DEFAULT_USER_ID) are appropriate and necessary for the stated purpose. The concern is that the registry metadata claims 'no required env vars' while the SKILL.md and script require sensitive credentials—this mismatch is misleading and dangerous if users assume no secrets are needed. The skill requests only the service-specific credentials it needs (no unrelated secrets).

Persistence & Privilege

The skill does not request always:true and does not attempt to modify other skills or system-wide configuration. It runs as an on-demand script and requires explicit environment setup; privilege/persistence requests are minimal and appropriate.

Scan Findings in Context

[no_pre_scan_signals] expected: Static pre-scan found no injection signals. That is plausible because the skill is mostly a shell script and documentation. Absence of automatic flags does not imply correctness—manual review found issues (missing dependency jq, metadata mismatch, JSON-escaping bug).

What to consider before installing

This skill does what it says (Volcengine TTS → convert → Feishu). Before installing or running it: 1) Treat FEISHU_APP_SECRET and VOLC_API_KEY as sensitive — use a secrets manager or ensure ~/.openclaw/.env is protected. 2) Do not rely on the registry metadata: the skill DOES require VOLC_API_KEY, VOLC_RESOURCE_ID, FEISHU_APP_ID and FEISHU_APP_SECRET. 3) Ensure the host has ffmpeg and jq installed (SKILL.md only mentions ffmpeg). 4) Review and test the script in a safe environment — the script embeds user text directly into JSON bodies without escaping and has a probable tmp-filename bug; these should be fixed to avoid malformed requests or accidental file collisions. 5) Create a Feishu app with minimal required permissions and rotate keys if you test with production credentials. If you want to proceed, ask the author to (a) correct registry metadata to list required env vars, (b) document jq as a required tool, and (c) fix the tmp filename and JSON-escaping in scripts.

飞书语音回复技能 (Feishu Voice Reply)

描述

使用火山引擎 TTS 生成特色音色语音，通过飞书 API 发送语音消息的完整流程技能。支持 MP3 转 Opus 格式、自动上传和发送。

触发词

• 语音回复
• 发送语音
• TTS 语音
• 飞书语音
• @voice

前置配置

1. 环境变量设置

在 ~/.openclaw/.env 或系统环境变量中配置：

# 火山引擎 TTS 配置
export VOLC_API_KEY="你的火山引擎 API Key"
export VOLC_RESOURCE_ID="volc.service_type.10029"

# 飞书应用配置
export FEISHU_APP_ID="你的飞书 App ID"
export FEISHU_APP_SECRET="你的飞书 App Secret"

# 可选：默认接收者 Open ID
export FEISHU_DEFAULT_USER_ID="ou_xxxxxx"

2. 安装依赖

# 安装 ffmpeg（用于音频格式转换）
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

3. 火山引擎开通

1. 访问 https://www.volcengine.com/
2. 注册/登录账号
3. 开通语音合成服务
4. 获取 API Key
5. 创建资源包并获取 Resource ID

4. 飞书应用配置

1. 访问 https://open.feishu.cn/app
2. 创建企业自建应用
3. 获取 App ID 和 App Secret
4. 添加权限：
   • im:resource - 上传资源文件
   • im:message - 发送消息
   • contact:user.base:readonly - 读取用户信息
5. 发布应用

使用方法

命令行方式

# 基本用法（使用默认音色）
./scripts/feishu-voice-reply.sh "你好呀，这是测试语音"

# 指定音色
./scripts/feishu-voice-reply.sh "你好" "ICL_zh_female_tiaopigongzhu_tob"

# 指定音色和接收者
./scripts/feishu-voice-reply.sh "你好" "ICL_zh_female_tiaopigongzhu_tob" "ou_xxxxxx"

OpenClaw 方式

语音回复 "你好呀，我是语音助手"

可用音色

当前资源包可用音色

音色 ID	名称	风格	性别
ICL_zh_female_tiaopigongzhu_tob	调皮公主	活泼可爱	女
zh_male_beijingxiaoye_emo_v2_mars_bigtts	北京小爷	emo 北京腔	男

更多音色

完整音色列表: 火山引擎音色列表

女声音色（部分）

• 弯弯笑 zh_female_wanwanxiao_mars_bigtts - 甜美
• 晶晶 zh_female_jingjing_mars_bigtts - 清新
• 轻婉 zh_female_qingwan_mars_bigtts - 温柔
• 新晴 zh_female_xinqing_mars_bigtts - 阳光
• 甜美 zh_female_tianmei_mars_bigtts - 甜美

男声音色（部分）

• 北京小爷 zh_male_beijingxiaoye_mars_bigtts - 北京腔
• 爽快 zh_male_shuangkuai_mars_bigtts - 爽朗
• 青春 zh_male_qingchun_mars_bigtts - 青春

注意: 以上音色需要开通对应的资源包才能使用。

执行流程

用户输入文本
    ↓
1. 调用火山引擎 TTS API → 生成 MP3 音频
    ↓
2. 使用 ffmpeg 转换 → Opus 格式 (32kbps)
    ↓
3. 调用飞书 API → 获取 Access Token
    ↓
4. 上传 Opus 文件 → 获取 file_key
    ↓
5. 发送语音消息 → 飞书用户

文件结构

feishu-voice-reply-clean/
├── SKILL.md                      # 技能说明（本文件）
├── README.md                     # 使用文档
├── package.json                  # 包配置
├── scripts/
│   └── feishu-voice-reply.sh     # 自动化脚本
└── config/
    └── feishu-voice-config.json  # 配置模板

错误处理

错误	原因	解决方案
resource ID is mismatched	音色不在资源包中	更换可用音色
99991661	缺少 access token	检查飞书应用配置
99992402	缺少 receive_id_type	已自动处理
ffmpeg not found	未安装 ffmpeg	安装 ffmpeg
VOLC_API_KEY not set	未配置环境变量	设置环境变量

配置文件说明

环境变量

变量名	说明	是否必需
VOLC_API_KEY	火山引擎 API Key	✅ 必需
VOLC_RESOURCE_ID	火山引擎资源 ID	✅ 必需
FEISHU_APP_ID	飞书应用 App ID	✅ 必需
FEISHU_APP_SECRET	飞书应用 App Secret	✅ 必需
FEISHU_DEFAULT_USER_ID	默认接收者 Open ID	❌ 可选

配置模板

复制 config/feishu-voice-config.json 为 config/feishu-voice-config.local.json 并进行个性化配置。

安全提示

• ⚠️ 不要将 API Key 和 App Secret 提交到代码仓库
• ⚠️ 使用环境变量存储敏感信息
• ✅ 配置文件已加入 .gitignore
• ✅ 生产环境使用独立的密钥管理

相关文档

• 火山引擎 TTS 文档
• 火山引擎音色列表
• 飞书开放平台
• 飞书消息类型

更新日志

v1.0.0 (2026-03-13)

• ✅ 初始版本发布
• ✅ 支持火山引擎 TTS 多音色
• ✅ 支持飞书语音消息发送
• ✅ 自动 MP3 转 Opus 格式
• ✅ 完整错误处理
• ✅ 详细文档

---

最后更新：2026-03-13 | 作者：沉寂 (chenji) | License: MIT