OpenClaw 音频/语音消息处理全指南:自动转写、模型回退与群聊 Mention 预检
OpenClaw 音频/语音消息处理全指南:自动转写、模型回退与群聊 Mention 预检
本指南聚焦 OpenClaw 的
tools.media.audio媒体理解(Media Understanding)能力:从入站语音消息的定位、下载与尺寸校验,到本地 CLI 与云端 Provider 的自动探测和逐条回退,再到转写结果如何注入回复、回显到聊天,以及 Telegram 群组requireMention场景下的音频预检(Preflight)转写。读完本文,你将掌握tools.media.audio全部配置参数的含义与取值,能够独立搭建“Provider + CLI 双保险”的转写链路,并理解 OpenClaw 在--verbose下如何记录转写决策。文中所有结论均可追溯至仓库内的 docs/nodes/audio.md 文档与 media-understanding 目录下的源码实现。
一、音频理解的整体工作流
在 OpenClaw 中,语音消息的转写归属于「媒体理解(Media Understanding)」管线。当音频理解被启用(或自动探测命中)时,OpenClaw 会依次执行如下步骤(详见 docs/nodes/audio.md):
- 定位首个音频附件:从入站消息的
MediaPaths/MediaUrls(即MsgContext中的媒体字段)中识别出第一个音频附件。附件可以是本地路径(含file://前缀)或远程 URL;如需下载,OpenClaw 会自动下载(normalizeAttachmentPath会同时做 Windows 网络路径校验,见 media-understanding/attachments.normalize.ts)。 - 强制
maxBytes上限:在把音频发送给每个模型条目之前,OpenClaw 会先校验文件大小,超过maxBytes(默认 20MB)的附件对该条目直接跳过,转而尝试下一个条目。 - 按顺序执行第一个可用模型条目:条目类型分为
provider(云端 API)与cli(本地命令行工具)两种,按配置顺序逐个尝试。 - 失败/跳过时尝试下一个条目:如果某个条目因超时、尺寸超限、无输出等原因失败,管线会继续尝试下一条(
runAttachmentEntries的循环逻辑见 media-understanding/runner.ts)。 - 成功后改写
Body并设置{{Transcript}}:转写成功时,OpenClaw 会把消息体中的<media:audio>占位符替换为[Audio]区块(具体格式见下文),同时将Transcript注入MsgContext,供模板以{{Transcript}}引用。
命令解析与转写结果
转写成功后,CommandBody / RawBody 会被设置为转写文本,因此斜杠命令(slash command)依然能够正常工作——例如用户发来一段语音说“/help”,转写后依然会命中命令解析。这一点由 media-understanding/apply.ts 中的逻辑保证:当音频输出存在且没有原始用户文本时,CommandBody 与 RawBody 直接取转写文本;若消息本身带有文本,则保留原始用户文本。
Verbose 日志
在 --verbose 模式下,OpenClaw 会记录转写何时执行、何时替换消息体,以及每次尝试的决策摘要(formatDecisionSummary 会输出 capability: outcome (成功/总数) via provider/model reason=原因,见 media-understanding/runner.entries.ts)。排查“语音没被转写”或“走了哪个模型”时,--verbose 是首选工具。
二、自动探测(默认行为)
如果你没有配置 tools.media.audio.models,且 tools.media.audio.enabled 未被显式设为 false,OpenClaw 会按以下顺序自动探测,并在第一个可用的选项处停止(实现见 media-understanding/runner.ts 的 resolveAutoEntries):
- 本地 CLI(若已安装)
sherpa-onnx-offline:需要环境变量SHERPA_ONNX_MODEL_DIR,且该目录下必须包含encoder.onnx、decoder.onnx、joiner.onnx与tokens.txt四个文件,缺一不可(见resolveSherpaOnnxEntry)。whisper-cli(来自whisper-cpp):优先使用WHISPER_CPP_MODEL指向的模型文件,未设置或文件不存在时回退到内置的 tiny 模型(resolveLocalWhisperCppEntry中默认路径为/opt/homebrew/share/whisper-cpp/for-tests-ggml-tiny.bin)。whisper(Python CLI):默认使用turbo模型,可自动下载模型(resolveLocalWhisperEntry)。
- Gemini CLI(
gemini):通过read_many_files工具读取媒体文件并输出纯文本。OpenClaw 会先执行一次探测调用(--output-format json ok,8 秒超时)确认 CLI 可用(probeGeminiCli)。 - Provider 密钥:依次检查 OpenAI → Groq → Deepgram → Google(
AUTO_AUDIO_KEY_PROVIDERS,见 media-understanding/defaults.ts),并进一步覆盖 Mistral(voxtral-mini-latest)。
要彻底关闭自动探测,设置 tools.media.audio.enabled: false 即可;要自定义转写后端,则配置 tools.media.audio.models。
关于二进制探测的注意事项
二进制探测在 macOS / Linux / Windows 上是“尽力而为”(best-effort)的:
- 需确保 CLI 位于
PATH中(OpenClaw 会展开~前缀并遍历PATH各目录,Windows 下还会按PATHEXT尝试.EXE/.CMD/.BAT/.COM等后缀,见findBinary/candidateBinaryNames); - 若要使用不在
PATH中的二进制,请在 CLI 条目中给出完整命令路径,或显式配置一个带完整路径的 CLI 模型条目。
三、配置示例:从单 Provider 到多级回退
1. Provider + CLI 回退(OpenAI + Whisper CLI)
这是最推荐的“双保险”组合:云端 Provider 优先,本地 CLI 兜底。完整配置如下(源自 docs/nodes/audio.md):
{
tools: {
media: {
audio: {
enabled: true,
maxBytes: 20971520,
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
{
type: "cli",
command: "whisper",
args: ["--model", "base", "{{MediaPath}}"],
timeoutSeconds: 45,
},
],
},
},
},
}
要点说明:
maxBytes: 20971520即 20MB(20 * 1024 * 1024),与DEFAULT_MAX_BYTES.audio一致;args中的{{MediaPath}}是模板占位符,运行时会被替换为实际媒体路径;可用占位符还包括{{MediaDir}}、{{OutputDir}}、{{OutputBase}}、{{Prompt}}、{{MaxChars}}(见 media-understanding/runner.entries.ts 的runCliEntry);timeoutSeconds: 45覆盖默认 60 秒超时;CLI 默认超时为 60 秒,请保持合理取值以免阻塞回复队列。
2. 仅 Provider + 作用域门控(Scope Gating)
通过 scope 可以对不同会话类型启用/禁用转写,规则采用**首条命中(first-match wins)**策略:
{
tools: {
media: {
audio: {
enabled: true,
scope: {
default: "allow",
rules: [{ action: "deny", match: { chatType: "group" } }],
},
models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
},
},
},
}
scope.default取值allow/deny,无匹配规则时生效;rules[].match支持channel、chatType(会被规范化为direct、group、room)与keyPrefix(匹配会话 key 前缀);- 判定逻辑实现见 media-understanding/scope.ts,入口调用在 media-understanding/resolve.ts 的
resolveScopeDecision。
3. 仅 Provider(Deepgram)
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "deepgram", model: "nova-3" }],
},
},
},
}
- 使用 Deepgram 时,OpenClaw 会读取
DEEPGRAM_API_KEY环境变量(Provider 认证遵循标准模型认证顺序:认证 Profile → 环境变量 →models.providers.*.apiKey); - Deepgram 额外支持
detectLanguage、punctuate、smartFormat兼容参数(buildDeepgramCompatQuery,见 media-understanding/runner.entries.ts); - Deepgram 搭建细节可参考 providers/deepgram。
4. 仅 Provider(Mistral Voxtral)
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
},
},
},
}
Mistral 搭建细节可参考 providers/mistral。voxtral-mini-latest 也是 DEFAULT_AUDIO_MODELS 中 Mistral 的默认模型(见 media-understanding/defaults.ts)。
5. 回显转写到聊天(opt-in)
默认情况下,OpenClaw 不会把转写结果回发给用户;如需让用户确认“Agent 听到了什么”,可开启回显:
{
tools: {
media: {
audio: {
enabled: true,
echoTranscript: true, // default is false
echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
},
},
},
}
echoTranscript: true会在 Agent 处理前,把转写确认消息发回原始聊天(实现见 media-understanding/echo-transcript.ts,默认格式常量DEFAULT_ECHO_TRANSCRIPT_FORMAT = '📝 "{transcript}"');echoFormat支持{transcript}占位符自定义文案;- 回显是 best-effort 的:若通道不可投递或发送失败,仅记日志,不会抛错中断流程。
四、核心参数速查表
以下参数均定义于 tools.media.audio 下(类型定义见 config/types.tools.ts 的 MediaUnderstandingConfig):
| 参数 | 默认值 | 说明 |
|---|---|---|
enabled |
未配置时自动探测 | 设为 false 彻底关闭音频理解 |
maxBytes |
20MB(20971520) | 发送给每个模型条目前的尺寸上限,超限跳过该条目 |
maxChars |
不设(完整转写) | 转写输出最大字符数,音频默认全量输出(区别于图片/视频的 500 字符默认值) |
timeoutSeconds |
60 | 单条目超时(秒),最小下限 1 秒(resolveTimeoutMs 会 Math.max(1000, ...)) |
language |
无 | 转写语言提示,透传给 Provider 的 language 字段 |
prompt |
"Transcribe the audio." |
提示词覆盖;音频场景不会自动附加 maxChars 说明 |
scope |
允许 | 作用域门控,{ default, rules: [{ action, match: { channel, chatType, keyPrefix } }] } |
attachments |
{ mode: "first", maxAttachments: 1 } |
附件选择策略,mode: "all" 可处理多条语音 |
models |
自动探测 | 有序模型条目列表,支持 provider / cli 两种类型 |
echoTranscript |
false |
是否回显转写确认到原始聊天 |
echoFormat |
'📝 "{transcript}"' |
回显文案模板,占位符 {transcript} |
baseUrl / headers / providerOptions |
无 | 音频 Provider 请求的覆盖项(baseUrl、请求头、Provider 专属 query 参数) |
模型条目(entry)级参数
models[] 中的每个条目还支持独立覆盖(MediaUnderstandingModelConfig):
provider/model:Provider id 与模型 id;type: "cli"+command/args:改用本地 CLI(args支持模板占位符);maxBytes/maxChars/timeoutSeconds:条目级覆盖全局默认;prompt:条目级提示词覆盖;language:条目级语言提示;profile/preferredProfile:指定使用的认证 Profile;baseUrl/headers/providerOptions:条目级请求覆盖(优先级:entry > config > providerConfig)。
优先级合并逻辑见 media-understanding/runner.entries.ts 的 resolveProviderExecutionContext(headers 按 providerConfig → config → entry 顺序合并)。
五、多附件处理与转写注入格式
处理多条语音
默认只处理第一个匹配的音频附件。通过 attachments 配置可处理多条(类型见 MediaUnderstandingAttachmentsConfig):
{
tools: {
media: {
audio: {
enabled: true,
attachments: {
mode: "all",
maxAttachments: 3, // 默认 1
prefer: "first", // first | last | path | url
},
models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
},
},
},
}
mode: "first"(默认)只取第一个;mode: "all"配合maxAttachments可处理多条;prefer控制排序偏好:first/last/path(有本地路径的优先)/url(有 URL 的优先);- 已通过预检转写的附件(
alreadyTranscribed: true)会被跳过,避免重复转写(见 media-understanding/attachments.select.ts)。
转写注入 Body 的格式
转写成功后,消息体中的 <media:audio> 会被替换为(见 media-understanding/format.ts 的 formatMediaUnderstandingBody):
[Audio]
Transcript:
<转写文本>
多条音频时显示 [Audio 1/2]、[Audio 2/2] 并各自携带转写;{{Transcript}} 模板变量在单条时直接为转写文本,多条时按 Audio 1:\n... 分行拼接(formatAudioTranscripts)。
六、限制、边界与代理支持
尺寸与空文件
- 默认尺寸上限 20MB(
tools.media.audio.maxBytes),超出上限的音频对该模型条目跳过,并尝试下一个条目; - 小于 1024 字节的音频(几乎肯定是空文件/损坏文件)会在进入 Provider/CLI 之前被跳过,避免 Whisper 等接口返回无意义的报错(常量
MIN_AUDIO_FILE_BYTES = 1024,见 media-understanding/defaults.ts,断言逻辑见assertMinAudioSize); maxChars默认不设(完整转写),需要截断输出时可设tools.media.audio.maxChars或条目级maxChars;- CLI stdout 输出上限为 5MB(
CLI_OUTPUT_MAX_BUFFER),请保持 CLI 输出简洁,避免被截断。
Provider 认证顺序
Provider 认证遵循标准模型认证顺序:认证 Profile(profile / preferredProfile)→ 环境变量 → models.providers.*.apiKey。使用 Deepgram 时读取 DEEPGRAM_API_KEY。底层实现通过 hasAvailableAuthForProvider / resolveApiKeyForProvider 完成,并支持 API Key 轮换(executeWithApiKeyRotation,见 agents/model-auth.ts 与 media-understanding/runner.entries.ts)。
代理环境变量
基于 Provider 的音频转写支持标准出站代理环境变量:
HTTPS_PROXYHTTP_PROXYhttps_proxyhttp_proxy
若未设置任何代理变量,则使用直连出口;若代理配置格式非法,OpenClaw 会记录警告并回退到直连(resolveProxyFetchFromEnv,见 infra/net/proxy-fetch.ts,注入点见 runProviderEntry 中的 resolveProxyFetchFromEnv())。
其他边界
- 音频 Provider 可通过
tools.media.audio覆盖baseUrl、headers、providerOptions; - OpenAI 自动默认模型为
gpt-4o-mini-transcribe;需要更高准确率可显式设置model: "gpt-4o-transcribe"; - 默认提示词为
"Transcribe the audio."(音频场景不会自动拼接字符上限说明,见 media-understanding/resolve.ts 的resolvePrompt)。
七、群聊中的 Mention 预检(Preflight Transcription)
当群聊设置了 requireMention: true 时,纯语音消息(无文本正文)默认会因为“未检测到 Mention”而被丢弃。为此,OpenClaw 引入了音频预检转写机制:在检查 Mention 之前先转写音频,使语音中的 @BotName 等提及模式也能被识别。
工作流程
- 若语音消息没有文本正文、且群组要求 Mention,OpenClaw 先执行一次 “preflight” 转写;
- 转写文本被用于检测提及模式(如
@BotName、emoji 触发词); - 若命中提及,消息继续走完整的回复管线;
- 转写结果参与提及判定,语音消息由此可通过 Mention 门控。
回退行为
- 若预检转写失败(超时、API 错误等),消息回退到纯文本提及检测——这保证了“文本 + 音频”混合消息永远不会被错误丢弃(实现见 media-understanding/audio-preflight.ts:预检失败只记日志、不抛异常);
- 预检成功的附件会标记
alreadyTranscribed = true,主媒体理解阶段不会再重复转写(media-understanding/audio-preflight.ts 与 media-understanding/attachments.select.ts 配合实现); - 预检只处理第一个音频附件,其余音频在主媒体理解阶段统一处理。
按群组/主题关闭预检(Telegram)
// 按群组关闭
{
channels: {
telegram: {
groups: {
"<chatId>": { disableAudioPreflight: true },
},
},
},
}
// 按话题(topic/thread)覆盖:true 跳过,false 强制启用
{
channels: {
telegram: {
groups: {
"<chatId>": {
topics: {
"<threadId>": { disableAudioPreflight: false },
},
},
},
},
},
}
- 默认值为
false(满足 mention 门控条件时预检启用); - 话题级配置优先级高于群组级:
topicConfig.disableAudioPreflight ?? groupConfig.disableAudioPreflight(见 telegram/src/bot-message-context.body.ts); - 触发预检的完整条件:
isGroup && requireMention && hasAudio && !hasUserText && mentionRegexes.length > 0 && !disableAudioPreflight(同一文件); - 对应测试覆盖了“群组关闭预检”“话题覆盖群组”等场景,见 telegram/src/bot-message-context.audio-transcript.test.ts。
实战示例
在 requireMention: true 的 Telegram 群组中,用户发送语音消息说“Hey @Claude, what's the weather?”(没有附带任何文字)。预检流程会:转写语音 → 在转写文本中检测到 @Claude 提及 → 消息通过 Mention 门控 → Agent 正常回复天气。若未启用预检,该语音消息会因“无文本、无提及”而被静默丢弃。
八、已知陷阱(Gotchas)
- Scope 规则是首条命中制:
chatType会被规范化为direct、group、room,规则顺序即优先级; - CLI 必须退出码为 0 且输出纯文本:如果 CLI 输出 JSON,需要自行处理,例如用
jq -r .text提取文本(可把jq作为 args 的一部分); parakeet-mlx的文件输出约定:若传入--output-dir,且--output-format为txt(或省略),OpenClaw 会读取<output-dir>/<media-basename>.txt;非txt格式回退到 stdout 解析(见resolveParakeetOutputPath,media-understanding/runner.entries.ts);- 超时控制:
timeoutSeconds默认 60 秒,过大的超时可能阻塞回复队列; - 预检只转写第一个音频附件,多附件场景下其余音频在主媒体理解阶段处理;
- 本地模型文件必须齐全:使用
sherpa-onnx-offline时,SHERPA_ONNX_MODEL_DIR下必须同时存在 encoder/decoder/joiner/tokens 四个文件,否则该条目被判定为不可用; - 转写结果注入:成功转写会改写
Body(替换为[Audio]区块)并设置CommandBody/RawBody,从而让斜杠命令照常工作,这也是--verbose下可观测的关键行为之一。
九、快速排障清单
- 语音没被转写? 先确认
tools.media.audio.enabled未被设为false;用--verbose查看audio: ...决策日志与reason=(常见为maxBytes超限、tooSmall空文件、无可用认证等)。 - 走了哪个后端?
--verbose下via provider/model会显示实际命中的条目;若想强制指定,配置tools.media.audio.models即可。 - CLI 条目不生效? 确认命令在
PATH中(或给出完整路径),CLI 退出码为 0,且 stdout 是纯文本(JSON 需用jq -r .text处理)。 - 群聊语音被忽略? 检查
requireMention配置与disableAudioPreflight(群组/话题级),并用预检流程验证提及是否被转写识别。 - 转写被截断? 检查
maxChars(音频默认无上限)与 CLI 5MB 的 stdout 上限。 - 接口报错? 确认 Provider 认证顺序(Profile → 环境变量 →
models.providers.*.apiKey),Deepgram 需设置DEEPGRAM_API_KEY;代理场景请确认HTTPS_PROXY/HTTP_PROXY等变量格式正确。
以上排障要点均与 docs/nodes/audio.md 中的 Notes & limits、Gotchas 章节一一对应,并可在 media-understanding 目录的源码与测试(如 media-understanding/runner.auto-audio.test.ts、media-understanding/runner.skip-tiny-audio.test.ts、media-understanding/runner.proxy.test.ts)中找到验证依据。