音频 / 语音消息 — 2026-01-17

已支持的能力

媒体理解（音频）：开启音频理解（或自动检测到）后，OpenClaw 会：
1. 找到第一个音频附件（本地路径或 URL），按需下载。
2. 发送给每个模型条目前检查 maxBytes 限制。
3. 按顺序运行第一个符合条件的模型条目（provider 或 CLI）。
4. 如果失败或被跳过（文件太大/超时），尝试下一个条目。
5. 成功后，用 [Audio] 块替换 Body，并设置 {{Transcript}}。
命令解析：转写成功后，CommandBody/RawBody 会被设为转写文本，斜杠命令照常工作。
详细日志：--verbose 模式下，转写运行和正文替换都会写入日志。

自动检测（默认行为）

如果你没有配置模型，且 tools.media.audio.enabled 没有设为 false， OpenClaw 会按以下顺序自动检测，找到第一个可用的就停：

本地 CLI（如果已安装）
- sherpa-onnx-offline（需要 SHERPA_ONNX_MODEL_DIR 包含 encoder/decoder/joiner/tokens）
- whisper-cli（来自 whisper-cpp；使用 WHISPER_CPP_MODEL 或内置的 tiny 模型）
- whisper（Python CLI；会自动下载模型）
Gemini CLI（gemini），使用 read_many_files
Provider API 密钥（OpenAI → Groq → Deepgram → Google）

要关闭自动检测，设置 tools.media.audio.enabled: false。要自定义，设置 tools.media.audio.models。注意：二进制文件检测在 macOS/Linux/Windows 上属于尽力而为；请确保 CLI 在 PATH 上（支持 ~ 展开），或者用完整路径指定 CLI 模型。

配置示例

Provider + CLI 回退（OpenAI + Whisper CLI）

{
  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,
          },
        ],
      },
    },
  },
}

仅 Provider，带作用域限制

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

仅 Provider（Deepgram）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

仅 Provider（Mistral Voxtral）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

把转写文本回显到聊天（需手动开启）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // 默认 false
        echoFormat: '📝 "{transcript}"', // 可选，支持 {transcript} 占位符
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

补充说明和限制

Provider 认证遵循标准模型认证顺序（auth profiles、环境变量、models.providers.*.apiKey）。
使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。
Deepgram 配置详情：Deepgram（音频转写）。
Mistral 配置详情：Mistral。
音频 Provider 可通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。
默认大小上限为 20MB（tools.media.audio.maxBytes）。超出限制的音频会跳过当前模型，尝试下一个。
低于 1024 字节的极小/空音频文件会在 provider/CLI 转写前直接跳过。
音频的默认 maxChars 为不限（保留完整转写）。可通过 tools.media.audio.maxChars 或每条目的 maxChars 来截断输出。
OpenAI 自动检测默认使用 gpt-4o-mini-transcribe；设置 model: "gpt-4o-transcribe" 可获得更高精度。
用 tools.media.audio.attachments 处理多条语音消息（mode: "all" + maxAttachments）。
转写文本可在模板中通过 {{Transcript}} 引用。
tools.media.audio.echoTranscript 默认关闭；开启后会在 agent 处理前，把转写确认发回原始聊天。
tools.media.audio.echoFormat 用于自定义回显文本（占位符：{transcript}）。
CLI 标准输出上限 5MB；保持 CLI 输出简洁。

代理环境变量支持

基于 Provider 的音频转写支持标准出站代理环境变量：

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

没设代理环境变量时走直连。代理配置格式错误时，OpenClaw 会记录警告并回退到直连。

群组中的提及检测

设置了 requireMention: true 的群聊中，OpenClaw 现在会先转写音频，再检查提及。这样即使语音消息中包含提及词，也能被正确处理。

工作原理：

如果语音消息没有文本正文，且群组要求提及，OpenClaw 会执行一次”预检转写”。
检查转写文本中是否存在提及模式（如 @BotName、emoji 触发词）。
如果找到提及，消息进入完整的回复流程。
转写文本用于提及检测，让语音消息能通过提及门控。

回退行为：

预检转写失败时（超时、API 错误等），消息仅基于纯文本进行提及检测。
这保证了混合消息（文本 + 音频）永远不会被误丢弃。

按 Telegram 群组/话题关闭：

设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true 可跳过该群组的预检转写提及检查。
设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 可按话题覆盖（true 跳过，false 强制开启）。
默认为 false（在需要提及门控的场景下启用预检）。

举个例子： 用户在一个设置了 requireMention: true 的 Telegram 群里发了一条语音：“嘿 @Claude，今天天气怎么样？“语音被转写，提及被检测到，agent 正常回复。

常见坑

作用域规则采用首条匹配。chatType 标准化为 direct、group 或 room。
确保你的 CLI 以 exit code 0 退出并输出纯文本；JSON 输出需要通过 jq -r .text 处理。
对于 parakeet-mlx，如果传了 --output-dir，当 --output-format 为 txt（或省略）时，OpenClaw 会读取 <output-dir>/<media-basename>.txt；非 txt 格式回退到解析标准输出。
超时设置要合理（timeoutSeconds，默认 60 秒），避免阻塞回复队列。
预检转写只处理第一个音频附件用于提及检测。其余音频在主媒体理解阶段处理。