Feishu Voice (ElevenLabs)

核心用法

Feishu Voice 是一个专为飞书（Lark）平台设计的语音消息处理工具，整合 ElevenLabs 的 TTS（文本转语音）与 STT（语音转文本）能力，实现双向语音通信。

发送语音（TTS）：通过 scripts/feishu-voice-send.sh 脚本，将文本转换为语音并发送至指定用户或群组。需配置 ElevenLabs API Key、语音 ID、模型 ID 及飞书应用凭证。

接收转录（STT）：通过 scripts/feishu-voice-stt.sh 将收到的 .ogg 语音文件转录为文本。若 OpenClaw 未直接传递文件，支持通过 Feishu API 手动下载后处理。

显著优点

• 填补官方缺陷：明确指出并绕过 OpenClaw asVoice 参数对飞书不生效的问题
• 工业级语音合成：ElevenLabs 提供高质量多语言语音，支持 eleven_multilingual_v2 等先进模型
• 自动语言检测：STT 使用 scribe_v1 模型，无需指定目标语言
• 灵活的凭证获取：支持从 openclaw.json 配置文件自动提取飞书凭证，降低配置负担
• 标准飞书协议：严格遵循飞书 im:message:send_as_bot 和 im:file 权限体系

潜在缺点与局限性

• 付费门槛：ElevenLabs 需付费计划才能使用库级语音，存在持续成本
• 外部依赖重：依赖 ffmpeg/ffprobe、sag CLI、Python3 等多个本地工具
• 手动 fallback 繁琐：当 OpenClaw 未传递附件时，需手动调用三步 API 流程获取文件
• 飞书格式限制：必须使用 "audio" msg_type，易与 "media"/"file" 混淆导致发送失败
• 语音 ID 需手动配置：无语音浏览/选择交互，用户需自行到 elevenlabs.io 查找并配置

适合人群

• 需要为飞书 Bot 添加语音交互能力的开发者
• 使用 OpenClaw 框架且受限于 asVoice 参数失效的用户
• 追求高质量 TTS 效果、愿意承担 ElevenLabs 付费成本的企业场景
• 具备 Linux/Shell 环境配置能力的技术团队

常规风险

• API 密钥泄露：ELEVENLABS_API_KEY、FEISHU_APP_SECRET 等敏感信息以环境变量形式管理，需确保 shell history 和配置文件权限安全
• 成本失控：ElevenLabs 按字符/时长计费，高频调用可能导致账单激增
• 网络依赖：所有语音处理依赖 ElevenLabs 云服务，离线场景不可用
• 格式兼容性：飞书语音消息为 .ogg/.opus 格式，若 ElevenLabs API 或本地 ffmpeg 版本不兼容可能导致转录失败
• 权限配置错误：飞书应用需同时申请 im:message:send_as_bot 和 im:file 权限，遗漏会导致消息发送或文件下载失败

核心用法

Feishu Voice 是一个专为飞书（Feishu/Lark）平台设计的语音消息处理技能，集成 ElevenLabs 领先的 AI 语音技术，实现双向语音通信能力：

语音发送（TTS）：通过 ElevenLabs 文本转语音引擎，将文字转换为自然人声，以飞书原生语音消息形式发送给指定用户或群聊。支持多语言语音合成，可配置不同音色。

语音接收（STT）：自动识别飞书接收到的语音消息（.ogg/.opus 格式），使用 ElevenLabs Scribe 模型转写为文字，支持自动语言检测。

使用方法简洁：发送时调用 feishu-voice-send.sh "文本内容" <接收者ID>，接收时调用 feishu-voice-stt.sh /路径/音频.ogg 即可获取转录文本。

显著优点

1. 音质卓越：ElevenLabs 提供业界领先的神经语音合成，生成的语音自然流畅，接近真人发音，远优于传统 TTS 方案。

2. 无缝集成：深度适配飞书消息协议，发送的语音以原生 "audio" 类型呈现，接收方无需额外操作即可播放，体验与人工发送的语音消息完全一致。

3. 自动化工作流：可作为 Agent 工具链的一环，实现"文字指令 → 语音回复"或"语音询问 → 文字回答"的智能交互闭环，提升客服、通知等场景效率。

4. 多语言支持：ElevenLabs 多语言模型（eleven_multilingual_v2）覆盖主流语种，配合自动语言识别，满足国际化团队需求。

5. 代码质量扎实：脚本遵循 Bash 最佳实践，包含严格的错误处理（set -euo pipefail）、临时文件自动清理（trap 机制），避免资源泄漏。

潜在缺点与局限性

1. 外部依赖较重：必须预装 sag CLI、ffmpeg/ffprobe 等工具，且 ElevenLabs 需付费订阅才能使用优质音色，增加了部署门槛和持续成本。

2. 网络依赖性强：功能完全依赖 ElevenLabs 和飞书 API 的可用性，任何一方服务中断或限流都会导致功能失效，不适合离线或高稳定性要求的场景。

3. 数据来源风险：语音数据需上传至 ElevenLabs 云端处理，对于医疗、金融等敏感行业，可能存在数据跨境传输和隐私合规顾虑。

4. 输入限制未前置：脚本未对输入文本长度进行校验，超长文本可能导致 API 调用失败；错误输出被重定向，问题排查存在一定难度。

5. 来源可信度一般：T3 级别个人开发者作品，虽代码结构良好，但长期维护更新、安全漏洞响应等方面存在不确定性。

适合的目标群体

• 企业运营团队：需要批量发送语音通知、公告，提升信息触达率和人情味
• 智能客服场景：构建语音交互型客服 Agent，支持语音进、文字出或语音出的双向沟通
• 无障碍办公：为视障用户或偏好语音交互的员工提供便捷的飞书消息收发方式
• 多语言团队：跨国团队成员可用母语发送消息，系统自动转换为目标语言语音
• 效率工具开发者：作为 OpenClaw/Coze 等平台的工作流组件，扩展 IM 自动化能力

使用风险与注意事项

• API 密钥安全：ELEVENLABS_API_KEY、FEISHU_APP_ID/SECRET 须通过环境变量配置，避免硬编码或命令行暴露，建议配置在用户级配置文件而非全局环境
• 费用监控：ElevenLabs 按字符/时长计费，高频调用可能产生意外账单，建议设置用量告警
• 权限最小化：飞书应用仅申请 im:message:send_as_bot 和 im:file 必要权限，定期审查授权范围
• 隐私评估：语音内容上传至第三方云服务前，确认符合组织数据分级分类和跨境传输合规要求
• 依赖可用性：生产环境部署前验证 ffmpeg、sag 等工具版本兼容性，准备降级方案（如纯文字回复）
• 日志审计：建议启用网络流量监控，验证 API 调用仅访问预期的官方端点，防范供应链攻击