核心用法
Volcengine STT 是对字节跳动火山引擎（Volcano Engine/ARK）语音识别 API 的命令行封装，主要服务于 OpenClaw 代理生态中的语音转文字需求。核心入口为 transcribe.sh 脚本，接收音频文件路径后自动完成格式转换、API 调用和结果落盘。
基础调用模式：
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg脚本内置环境变量兜底机制：
- 默认端点：
https://ark.cn-beijing.volces.com/api/v3/audio/transcriptions - 默认模型：
doubao-seed-asr-1-0（豆包种子 ASR） - 认证方式：Bearer Token via
ARK_API_KEY
扩展参数支持定向输出（--out）、模型覆盖（--model）、原始 JSON 返回（--json）及语言提示（--language/--prompt），适配中文混排、术语保留等场景。
显著优点
1. 中文场景优化：豆包 ASR 模型针对中文语音识别、中英混合场景专项训练，中文准确率显著优于通用 Whisper 模型
2. 国产化合规：数据不出境，符合国内数据安全法规要求，适合政企、金融等敏感场景
3. 生态替代性：设计为 Whisper/OpenAI STT 的 drop-in 替代，迁移成本低
4. 多格式支持：火山引擎底层支持多种音频格式，脚本层屏蔽格式转换细节
5. Prompt 可控：支持通过 --prompt 传递上下文提示，优化专业术语、人名识别
潜在缺点与局限性
1. 地理与网络限制：服务端点固定为北京区域（cn-beijing），海外部署需考虑跨境延迟
2. 生态锁定：深度绑定火山引擎账号体系，模型选择受限于 ARK 平台供应列表
3. 计费透明度：火山引擎采用按用量计费，但脚本层未暴露用量查询接口，成本监控需额外对接
4. 调试信息有限：除 --json 模式外，错误详情暴露不足，API 限流、模型不可用等场景排障依赖手动抓包
5. 开源社区生态弱：相比 Whisper 社区，中文技术文档、第三方集成案例相对较少
适合人群
- 国内开发者：优先满足中文语音识别需求，避免海外服务延迟与合规风险
- OpenClaw 代理开发者：需在多代理系统中统一替换 STT 后端，保持接口兼容
- 企业合规场景：金融、政务、医疗等数据敏感行业，需国产化语音方案
- Telegram/Discord Bot 运营者：处理中文用户语音消息，追求识别准确率
常规风险
| 风险类别 | 说明 | 缓解建议 |
|---------|------|---------|
| 密钥泄露 | `ARK_API_KEY` 需以环境变量注入，误提交至版本控制将导致账号盗用 | 使用 `.env` 或机器级密钥管理，CI/CD 中配置 secret 扫描 |
| 成本失控 | 长音频、高并发场景下按调用时长计费可能产生意外账单 | 设置火山引擎账户余额告警，实施音频时长前置校验 |
| 服务可用性 | 火山引擎 API 存在单区域故障、限流可能 | 实现指数退避重试，关键业务准备 Whisper 降级方案 |
| 数据残留 | 音频上传至火山引擎服务端处理，存在短暂存储 | 审查火山引擎数据处理协议，敏感音频考虑边缘预处理 |
| 模型漂移 | `doubao-seed-asr-1-0` 为种子版本，后续可能迭代或下线 | 显式锁定模型版本，关注火山引擎变更公告 |