音频 / 语音消息（2026-01-17）

支持的功能

• 媒体理解（音频）：启用音频理解（或自动检测）时，OpenClaw 会：
  1. 定位第一个音频附件（本地路径或 URL），如需下载则自动下载。
  2. 在发送给每个模型条目前执行 maxBytes 检查。
  3. 按顺序运行第一个符合条件的模型条目（provider 或 CLI）。
  4. 如果失败或跳过（大小/超时），尝试下一个条目。
  5. 成功后，将 Body 替换为 [Audio] 块并设置 。
• 命令解析：转录成功时，CommandBody/RawBody 被设置为转录文本，斜杠命令仍然正常工作。
• 详细日志：开启 --verbose 时，会记录转录运行时机和 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 模型）
   • whisper（Python CLI；自动下载模型）
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 上是尽力而为的；确保 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，带 scope 门控

{
  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）。
• 转录结果可在模板中通过 访问。
• 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 现在会先转录音频，再检查@提及。这样即使@提及包含在语音消息中也能被正常处理。

工作原理：

1. 如果语音消息没有文字内容且群组需要@提及，OpenClaw 执行"预检"转录。
2. 检查转录文本中的@提及模式（例如 @BotName、emoji 触发词）。
3. 如果找到@提及，消息进入完整回复流水线。
4. 转录结果用于@提及检测，语音消息得以通过@门控。

回退行为：

• 如果预检期间转录失败（超时、API 错误等），消息根据纯文本@提及检测处理。
• 确保混合消息（文字 + 音频）不会被错误丢弃。

Telegram 群组/话题粒度关闭：

• 设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true 可跳过该群组的预检转录@提及检测。
• 设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 可按话题覆盖（true 跳过，false 强制开启）。
• 默认为 false（满足@门控条件时启用预检）。

示例： 用户在设置了 requireMention: true 的 Telegram 群组中发送语音"Hey @Claude，今天天气怎么样？"。语音被转录，检测到@提及，agent 回复。

注意事项

• Scope 规则使用首个匹配规则。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，默认 60s），避免阻塞回复队列。
• 预检转录只处理第一个音频附件用于@提及检测，其余音频在主媒体理解阶段处理。