voice-to-text

Voice to Text Skill

基于火山引擎 BigModel ASR 将语音转为文字。准确率和多语言能力远优于本地 whisper，且速度更快。

适用场景

1. 收到飞书语音消息（message_type: audio），需要自动识别语音内容
2. 收到音频文件附件（.ogg、.mp3、.wav）
3. 用户提到「语音识别」「语音转文字」「ASR」

强制规则（最高优先级）

当你收到语音消息或音频文件附件时：

• 必须且只能使用 本 Skill 的 asr.py 脚本来识别语音
• 禁止使用 whisper 命令或 openai-whisper skill
• 禁止 fallback：如果 asr.py 执行失败，直接将错误信息告知用户，不要改用 whisper

使用步骤

1. 确认音频来源（本地文件、URL 或飞书语音 file_key）。
2. 运行脚本前先 cd 到本技能目录：skills/voice-to-text。
3. 执行对应命令（见下方参数说明）。
4. 将脚本输出的文字当作用户发送的文本消息，理解其意图并正常回复。不需要额外说明"语音识别结果是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"