什么是 飞书语音消息插件？

飞书语音插件在文本 AI 智能体与飞书平台语音通信之间建立了无缝桥梁。通过利用 Openclaw Skills 的这一集成，开发者可以自动完成从文本字符串生成逼真音频并将其作为交互式语音气泡投递的过程。该插件处理了飞书 API 复杂的规范要求，包括音频转码为 opus 格式和元数据管理，确保每条消息都可播放并包含准确的时长信息。

该插件旨在增强团队参与感，简化了身份验证、文件上传和媒体格式化的难度。对于希望在 Openclaw Skills 框架内构建高级通知系统或交互式机器人的开发者来说，这是一个核心组件。

下载入口:https://github.com/openclaw/skills/tree/main/skills/franklu0819-lang/feishu-voice

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

飞书语音消息插件 应用场景

• 发送自动化的每日站会总结语音消息，提升团队参与度。
• 通过音频通知团队成员关键系统告警，确保紧急情况得到关注。
• 创建交互式 AI 机器人，以语音而非纯文本形式回复，提供更人性化的体验。
• 为长篇技术报告或状态更新提供音频备选方案，提高无障碍访问性。

1. 插件接收来自用户或智能体的文本输入，以及语音类型和语速的逻辑参数。
2. 利用 Openclaw Skills 库中的 zhipu-tts 集成生成高质量的 WAV 音频文件。
3. 使用 Ffmpeg 将生成的音频转码为飞书平台所需的特定 opus 格式。
4. Ffprobe 自动计算音频剪辑的精确整数时长，以确保在聊天界面中正确显示。
5. 使用具有必要 file_type 和 duration 元数据的租户访问令牌将文件上传到飞书服务器。
6. 最终的 API 调用将语音消息发送到指定的 Open ID 或群聊接收者。

飞书语音消息插件 配置指南

首先，确保您的环境中安装了必要的系统依赖：

sudo apt-get install ffmpeg jq

接下来，使用您的飞书和智谱 AI 凭据配置环境变量，以授权 Openclaw Skills 操作：

# 飞书应用凭据
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="your_secret"
export FEISHU_RECEIVER="ou_xxx"

# TTS 引擎凭据
export ZHIPU_API_KEY="your_zhipu_key"

最后，执行脚本发送您的第一条语音消息：

bash scripts/send_voice.sh "你好，这是一条通过 Openclaw Skills 发送的测试语音消息。"

飞书语音消息插件 数据架构与分类体系

该插件根据以下架构组织其技术要求和输出元数据：

name: feishu-voice
description: 飞书语音消息发送技能。将文本转换为语音并发送到飞书，支持 TTS 生成、格式转换、时长读取、文件上传和消息发送。
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["ffmpeg", "ffprobe", "jq"],
      "env": ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "ZHIPU_API_KEY"],
      "skills": ["zhipu-tts"]
    }
  }
}

飞书语音消息发送技能

将文本转换为语音消息发送到飞书，支持在飞书聊天窗口直接播放。

功能特性

• ? TTS 文字转语音（使用 zhipu-tts）
• ? 自动转换为 opus 格式（飞书要求）
• ? 读取音频时长
• ? 上传到飞书服务器
• ? 发送可播放的语音消息
• ? 支持多种声音和语速

前置要求

环境变量

# 飞书配置
export FEISHU_APP_ID="cli_xxx"              # 飞书应用 ID
export FEISHU_APP_SECRET="your_secret"      # 飞书应用密钥
export FEISHU_RECEIVER="ou_xxx"             # 接收者 Open ID（可选，默认从上下文获取）

# 智谱 AI 配置（用于 TTS）
export ZHIPU_API_KEY="your_zhipu_key"       # 智谱 API 密钥

必需工具

• ffmpeg - 音频格式转换
• ffprobe - 读取音频信息
• jq - JSON 处理

依赖技能

• zhipu-tts - 文字转语音

使用方法

基本用法

# 发送语音消息
bash scripts/send_voice.sh "你好，这是一条语音消息"

高级选项

# 指定声音和语速
bash scripts/send_voice.sh "你好" tongtong 1.2

# 可用声音：
# - tongtong (彤彤) - 默认女声，平衡音色
# - chuichui (锤锤) - 男声，深沉音色
# - xiaochen (小陈) - 年轻声音

# 语速范围：0.5 - 2.0（默认 1.0）

脚本说明

send_voice.sh

主脚本，完整的语音消息发送流程。

用法：

bash scripts/send_voice.sh <文本> [声音] [语速]

参数：

• 文本 (必需): 要转换为语音的文字
• 声音 (可选): tongtong, chuichui, xiaochen（默认：tongtong）
• 语速 (可选): 0.5-2.0（默认：1.0）

环境变量：

• FEISHU_APP_ID: 飞书应用 ID
• FEISHU_APP_SECRET: 飞书应用密钥
• FEISHU_RECEIVER: 接收者 Open ID（可选）

流程说明

1. TTS 生成: 使用 zhipu-tts 生成 WAV 格式音频
2. 格式转换: 使用 ffmpeg 转换为 opus 格式
3. 读取时长: 使用 ffprobe 获取音频时长（秒）
4. 上传文件: 上传到飞书，指定 file_type=opus 和 duration
5. 发送消息: 发送 msg_type=audio 消息

技术细节

音频格式要求

飞书语音消息要求：

• 格式: opus (OGG 容器)
• 编码: libopus
• 比特率: 24k
• 采样率: 24000 Hz
• 声道: 单声道

Duration 参数

关键: 必须在上传时提供 duration 参数（整数秒），否则时长显示为 0。

# 正确的上传方式
curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" r
  -F "file=@voice.opus" r
  -F "file_type=opus" r
  -F "duration=6"          # ← 关键参数

API 端点

故障排查

语音没有时长

问题: 发送的语音消息时长显示为 0

解决: 确保在上传时传递了 duration 参数（整数秒）

# 获取时长（四舍五入）
DURATION=$(ffprobe -v error -show_entries format=duration r
  -of default=noprint_wrappers=1:nokey=1 voice.opus | awk '{printf "%.0f", $1}')

# 上传时带上 duration
curl ... -F "duration=$DURATION"

无法播放

问题: 语音消息无法播放

可能原因:

1. 格式不是 opus
2. file_type 参数错误
3. 文件损坏

解决:

# 检查格式
ffprobe voice.opus

# 重新转换
ffmpeg -i input.wav -c:a libopus -b:a 24k voice.opus

API 权限错误

问题: 上传时返回权限错误

解决: 确保飞书应用有以下权限：

• im:message
• im:message:send_as_bot

完整示例

# 设置环境变量
export FEISHU_APP_ID="your_app_id_here"
export FEISHU_APP_SECRET="your_app_secret_here"
export ZHIPU_API_KEY="your_zhipu_key_here"

# 发送语音
bash /root/.openclaw/workspace/skills/feishu-voice/scripts/send_voice.sh r
  "你好，这是一条测试语音消息。"

注意事项

1. 时长限制: 智谱 TTS 单次最多 1024 字符
2. 整数时长: duration 必须是整数（四舍五入）
3. opus 格式: 飞书只接受 opus 格式的音频消息
4. 文件清理: 临时文件会自动清理

相关技能

• zhipu-tts: 文字转语音
• zhipu-asr: 语音转文字