OpenClaw 音频/语音消息处理全指南:自动转写、模型回退与群聊 Mention 预检

原创2026-10-14 15:25:331,995 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

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):

  1. 定位首个音频附件:从入站消息的 MediaPaths / MediaUrls(即 MsgContext 中的媒体字段)中识别出第一个音频附件。附件可以是本地路径(含 file:// 前缀)或远程 URL;如需下载,OpenClaw 会自动下载(normalizeAttachmentPath 会同时做 Windows 网络路径校验,见 media-understanding/attachments.normalize.ts)。
  2. 强制 maxBytes 上限:在把音频发送给每个模型条目之前,OpenClaw 会先校验文件大小,超过 maxBytes(默认 20MB)的附件对该条目直接跳过,转而尝试下一个条目。
  3. 按顺序执行第一个可用模型条目:条目类型分为 provider(云端 API)与 cli(本地命令行工具)两种,按配置顺序逐个尝试。
  4. 失败/跳过时尝试下一个条目:如果某个条目因超时、尺寸超限、无输出等原因失败,管线会继续尝试下一条(runAttachmentEntries 的循环逻辑见 media-understanding/runner.ts)。
  5. 成功后改写 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):

  1. 本地 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)。
  2. Gemini CLI(gemini):通过 read_many_files 工具读取媒体文件并输出纯文本。OpenClaw 会先执行一次探测调用(--output-format json ok,8 秒超时)确认 CLI 可用(probeGeminiCli)。
  3. 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_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_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 等提及模式也能被识别。

工作流程

  1. 若语音消息没有文本正文、且群组要求 Mention,OpenClaw 先执行一次 “preflight” 转写;
  2. 转写文本被用于检测提及模式(如 @BotName、emoji 触发词);
  3. 若命中提及,消息继续走完整的回复管线;
  4. 转写结果参与提及判定,语音消息由此可通过 Mention 门控。

回退行为

按群组/主题关闭预检(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 下可观测的关键行为之一。

九、快速排障清单

  1. 语音没被转写? 先确认 tools.media.audio.enabled 未被设为 false;用 --verbose 查看 audio: ... 决策日志与 reason=(常见为 maxBytes 超限、tooSmall 空文件、无可用认证等)。
  2. 走了哪个后端? --verbose 下 via provider/model 会显示实际命中的条目;若想强制指定,配置 tools.media.audio.models 即可。
  3. CLI 条目不生效? 确认命令在 PATH 中(或给出完整路径),CLI 退出码为 0,且 stdout 是纯文本(JSON 需用 jq -r .text 处理)。
  4. 群聊语音被忽略? 检查 requireMention 配置与 disableAudioPreflight(群组/话题级),并用预检流程验证提及是否被转写识别。
  5. 转写被截断? 检查 maxChars(音频默认无上限)与 CLI 5MB 的 stdout 上限。
  6. 接口报错? 确认 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)中找到验证依据。

登录后查看全文
openclaw-zero-token