Audio / Voice Notes — 2026-01-17

可用功能

  • Media understanding（audio）：如果启用了 audio understanding（或被自动检测启用），OpenClaw 会：

    1. 定位第一个音频附件（本地路径或 URL），必要时先下载。
    2. 在发送给每个 model entry 之前先校验 maxBytes。
    3. 按顺序运行第一个符合条件的 model entry（provider 或 CLI）。
    4. 如果失败或被跳过（例如 size/timeout），就尝试下一个 entry。
    5. 成功时，会用一个 [Audio] block 替换 Body，并设置 {{Transcript}}。
  • 命令解析：当转录成功时，CommandBody / RawBody 会被设置为 transcript，因此 slash commands 仍然可用。
  • Verbose logging：在 --verbose 模式下，我们会记录何时运行 transcription，以及何时它替换了 body。

自动检测（默认）

如果你没有配置 models，并且 tools.media.audio.enabled 没有被设置为 false，OpenClaw 会按以下顺序自动检测，并在找到第一个可用方案后停止：

  1. 本地 CLI（如果已安装）

    • sherpa-onnx-offline（要求设置 SHERPA_ONNX_MODEL_DIR，其中包含 encoder/decoder/joiner/tokens）
    • whisper-cli（来自 whisper-cpp；使用 WHISPER_CPP_MODEL 或内置的 tiny model）
    • whisper（Python CLI；会自动下载 models）
  2. Gemini CLI（gemini），使用 read_many_files
  3. Provider keys（OpenAI → Groq → Deepgram → Google）

如需关闭自动检测，请设置 tools.media.audio.enabled: false。 如需自定义，请设置 tools.media.audio.models。 注意：二进制检测在 macOS/Linux/Windows 上属于 best-effort；请确保 CLI 已在 PATH 中（我们会展开 ~），或者显式设置一个带完整命令路径的 CLI model。

配置示例

Provider + CLI fallback（OpenAI + Whisper CLI）

  1. {
  2.   tools: {
  3.     media: {
  4.       audio: {
  5.         enabled: true,
  6.         maxBytes: 20971520,
  7.         models: [
  8.           { provider: "openai", model: "gpt-4o-mini-transcribe" },
  9.           {
  10.             type: "cli",
  11.             command: "whisper",
  12.             args: ["--model", "base", "{{MediaPath}}"],
  13.             timeoutSeconds: 45,
  14.           },
  15.         ],
  16.       },
  17.     },
  18.   },
  19. }

仅 Provider，并带 scope gating

  1. {
  2.   tools: {
  3.     media: {
  4.       audio: {
  5.         enabled: true,
  6.         scope: {
  7.           default: "allow",
  8.           rules: [{ action: "deny", match: { chatType: "group" } }],
  9.         },
  10.         models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
  11.       },
  12.     },
  13.   },
  14. }

仅 Provider（Deepgram）

  1. {
  2.   tools: {
  3.     media: {
  4.       audio: {
  5.         enabled: true,
  6.         models: [{ provider: "deepgram", model: "nova-3" }],
  7.       },
  8.     },
  9.   },
  10. }

仅 Provider（Mistral Voxtral）

  1. {
  2.   tools: {
  3.     media: {
  4.       audio: {
  5.         enabled: true,
  6.         models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
  7.       },
  8.     },
  9.   },
  10. }

将 transcript 回显到聊天中（可选开启）

  1. {
  2.   tools: {
  3.     media: {
  4.       audio: {
  5.         enabled: true,
  6.         echoTranscript: true, // default is false
  7.         echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
  8.         models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
  9.       },
  10.     },
  11.   },
  12. }

说明与限制

  • Provider 鉴权遵循标准 model auth 顺序（auth profiles、环境变量、models.providers.*.apiKey）。
  • 当使用 provider: "deepgram" 时，会读取 DEEPGRAM_API_KEY。
  • Deepgram 配置详情见：Deepgram (audio transcription)。
  • Mistral 配置详情见：Mistral。
  • Audio providers 可以通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。
  • 默认大小上限为 20MB（tools.media.audio.maxBytes）。超出大小的音频会对当前 model 跳过，并尝试下一个 entry。
  • 小于 1024 bytes 的极小或空音频文件，会在 provider/CLI transcription 之前直接跳过。
  • Audio 默认 maxChars 不设置（即输出完整 transcript）。你可以设置 tools.media.audio.maxChars 或按 entry 单独设置 maxChars 来裁剪输出。
  • OpenAI 的自动默认 model 是 gpt-4o-mini-transcribe；如需更高精度，可设置 model: "gpt-4o-transcribe"。
  • 使用 tools.media.audio.attachments 可以处理多个 voice notes（mode: "all" + maxAttachments）。
  • Transcript 可通过模板变量 {{Transcript}} 使用。
  • tools.media.audio.echoTranscript 默认关闭；启用后，会在 agent 处理前先把 transcript 确认消息发送回原始聊天。
  • tools.media.audio.echoFormat 用于自定义回显文本（占位符：{transcript}）。
  • CLI stdout 有上限（5MB）；请保持 CLI 输出简洁。

代理环境支持

基于 provider 的 audio transcription 支持标准的出站代理环境变量：

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

如果没有设置 proxy 环境变量，则使用 direct egress。 如果 proxy 配置格式错误，OpenClaw 会记录 warning，并回退到 direct fetch。

群组中的 Mention Detection

当群聊设置了 requireMention: true 时，OpenClaw 现在会在检查 mentions 之前，先对音频进行转录。这样即使是语音消息中包含 mentions，也能被正确处理。

工作方式如下：

  1. 如果一条语音消息没有 text body，且该群开启了 require mentions，OpenClaw 会先执行一次“preflight” transcription。
  2. 然后检查 transcript 中是否包含 mention 模式（例如 @BotName、emoji triggers）。
  3. 如果检测到 mention，消息就会继续进入完整的 reply pipeline。
  4. Mention detection 会基于 transcript 执行，因此 voice notes 可以通过 mention gate。

回退行为：

  • 如果 preflight 阶段的 transcription 失败（timeout、API error 等），消息会退回为仅基于文本的 mention detection。
  • 这可以确保混合消息（text + audio）不会被错误丢弃。

按 Telegram group/topic 单独关闭：

  • 设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true，即可跳过该 group 的 preflight transcript mention 检查。
  • 设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight，即可按 topic 覆盖（true 表示跳过，false 表示强制启用）。
  • 默认值为 false（即当 mention-gated 条件匹配时，启用 preflight）。

示例：用户在一个设置了 requireMention: true 的 Telegram 群中发送一条语音，说的是 “Hey @Claude, what’s the weather?”。该语音会先被转录，检测到 mention，然后 agent 进行回复。

注意事项

  • Scope 规则采用 first-match wins。chatType 会被规范化为 direct、group 或 room。
  • 请确保你的 CLI 以 0 退出并输出纯文本；如果输出是 JSON，需要通过 jq -r .text 等方式先转换。
  • 对于 parakeet-mlx，如果你传入 --output-dir，当 --output-format 为 txt（或省略）时，OpenClaw 会读取 <output-dir>/<media-basename>.txt；非 txt 输出格式则回退为解析 stdout。
  • 请将超时设置控制在合理范围内（timeoutSeconds，默认 60 秒），以避免阻塞 reply queue。
  • Preflight transcription 在 mention detection 阶段只处理第一个 audio attachment。其他音频会在主 media understanding 阶段处理。