12.4 音频与语音

OpenClaw 支持音频/语音消息的自动转录功能,可将语音消息转换为文本并传递给 AI 模型处理。

工作原理

媒体理解(音频)

当启用音频理解功能(或自动检测)时,OpenClaw 执行以下步骤:

1. 定位第一个音频附件(本地路径或 URL)并在需要时下载
2. 在发送到每个模型条目之前强制执行 maxBytes 大小限制
3. 按顺序运行第一个符合条件的模型条目(提供商或 CLI)
4. 如果失败或跳过(大小/超时),则尝试下一个条目
5. 成功后,用 [Audio] 块替换 Body 并设置 {{Transcript}}

命令解析

转录成功后,CommandBody/RawBody 会设置为转录文本,因此斜杠命令仍然可以正常工作。

详细日志

使用 --verbose 参数时,会记录转录运行和替换正文的时间。

自动检测(默认)

如果未配置模型且 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 CLI 的 read_many_files 功能

3. 提供商密钥

按顺序尝试: OpenAI → Groq → Deepgram → Google

配置示例

提供商 + 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,
          },
        ],
      },
    },
  },
}

仅提供商 + 范围限制

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

仅提供商 (Deepgram)

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

注意事项与限制

• 提供商认证遵循标准模型认证顺序(认证配置文件、环境变量、models.providers.*.apiKey)
• 使用 provider: "deepgram" 时会使用 DEEPGRAM_API_KEY
• 音频提供商可以通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions
• 默认大小上限为 20MB (tools.media.audio.maxBytes)。超大音频会被跳过并尝试下一个条目
• 音频的默认 maxChars 为未设置(完整转录)。设置 tools.media.audio.maxChars 或每个条目的 maxChars 来裁剪输出
• OpenAI 自动默认使用 gpt-4o-mini-transcribe; 设置 model: "gpt-4o-transcribe" 以获得更高准确度
• 使用 tools.media.audio.attachments 处理多个语音消息(mode: "all" + maxAttachments)
• 转录文本可通过 {{Transcript}} 模板变量使用
• CLI 标准输出限制为 5MB; 保持 CLI 输出简洁

常见问题