Voice to Text Skill
基于火山引擎 BigModel ASR 将语音转为文字。准确率和多语言能力远优于本地 whisper，且速度更快。
适用场景
- 收到飞书语音消息（
message_type: audio），需要自动识别语音内容 - 收到音频文件附件（
.ogg、.mp3、.wav） - 用户提到「语音识别」「语音转文字」「ASR」
强制规则（最高优先级）
当你收到语音消息或音频文件附件时：
- 必须且只能使用 本 Skill 的
asr.py脚本来识别语音 - 禁止使用
whisper命令或 openai-whisper skill - 禁止 fallback：如果 asr.py 执行失败，直接将错误信息告知用户，不要改用 whisper
使用步骤
- 确认音频来源（本地文件、URL 或飞书语音 file_key）。
- 运行脚本前先
cd到本技能目录：skills/voice-to-text。 - 执行对应命令（见下方参数说明）。
- 将脚本输出的文字当作用户发送的文本消息，理解其意图并正常回复。不需要额外说明"语音识别结果是xxx"，直接回答用户的问题即可。
环境变量与鉴权
鉴权采用新版控制台方案，详见：快速入门（新版控制台）、API Key 使用。
使用前需配置：
- 推荐（新版控制台）：
MODEL_SPEECH_API_KEY— 在豆包语音新版控制台开通录音文件识别极速版，并创建/获取 API Key。 - 兼容旧版：若同时配置
MODEL_SPEECH_APP_ID与MODEL_SPEECH_API_KEY，则使用旧版 X-Api-App-Key / X-Api-Access-Key 鉴权。 - 可选：
MODEL_SPEECH_ASR_API_BASE（ASR API 端点，默认 BigModel Flash）、MODEL_SPEECH_ASR_RESOURCE_ID（资源 ID，默认volc.bigasr.auc_turbo）。 - 飞书相关：
FEISHU_TENANT_TOKEN（飞书 tenant_access_token，仅在使用--file-key模式时需要）。
脚本参数
| 参数 | 必填 | 说明 |
|---|---|---|
--file |
三选一 | 本地音频文件路径 |
--url |
三选一 | 音频文件的 URL 地址 |
--file-key |
三选一 | 飞书语音消息的 file_key |
--feishu-token |
否 | 飞书 tenant_access_token（也可通过 FEISHU_TENANT_TOKEN 环境变量设置） |
--appid |
否 | 火山引擎 ASR App ID（也可通过 MODEL_SPEECH_APP_ID 环境变量设置） |
--token |
否 | 火山引擎 ASR API Key（也可通过 MODEL_SPEECH_API_KEY 环境变量设置） |
--language |
否 | 语言代码，如 zh-CN、ja-JP、en-US（不传则自动识别） |
返回值说明
脚本输出纯文本到 stdout，即为用户说的话。如果失败，stdout 会包含以 [voice-to-text ERROR] 开头的错误信息。
飞书语音消息处理流程
收到 audio 消息 → 音频文件已下载到 /root/.openclaw/media/inbound/ → 执行 asr.py --file → 返回文字 → 当作用户消息处理
常用命令：
# 飞书语音文件（最常用，文件已被飞书插件自动下载）
python scripts/asr.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"
错误处理
- 若报错
PermissionError: MODEL_SPEECH_API_KEY... 需在环境变量中配置：提示用户按快速入门（新版控制台）开通录音文件识别极速版，并获取并配置MODEL_SPEECH_API_KEY，写入 workspace 下的环境变量文件后重试。 - 若报错
ASR 请求失败：根据错误码和信息提示用户检查 API 凭据及账号是否已开通豆包语音服务。 - 若报错
音频文件不存在或音频文件为空：检查文件路径是否正确。 - 遇到报错时直接告知用户具体错误，不要尝试用 whisper 替代。
参考文档
- 火山引擎 BigModel ASR
- 快速入门（新版控制台） — 鉴权与开通
- API Key 使用
示例
# 本地音频文件（最常用）
python scripts/asr.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"
# 音频 URL
python scripts/asr.py --url "https://example.com/audio.mp3"
# 指定语言
python scripts/asr.py --file "/path/to/audio.ogg" --language "ja-JP"
# 飞书 file_key（需要 tenant_token）
python scripts/asr.py --file-key "file_v2_xxxx" --feishu-token "t-g104xxx"
