Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

音频 / 语音留言（2026-01-17）

​

可用功能

• 媒体理解（音频）：如果启用了音频理解（或自动检测到），OpenClaw 会：
  1. 定位第一个音频附件（本地路径或 URL），并在需要时下载。
  2. 在发送到每个模型条目前强制执行 maxBytes。
  3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
  4. 如果失败或跳过（大小/超时），则尝试下一个条目。
  5. 成功后，将 Body 替换为 [Audio] 块，并设置 {{Transcript}}。
• 命令解析：转写成功后，CommandBody/RawBody 会被设置为转写文本，因此斜杠命令仍然可用。
• 详细日志：在 --verbose 下，我们会记录转写何时运行以及何时替换正文。

​

自动检测（默认）

1. 当前回复模型，当其提供商支持音频理解时。
2. 本地 CLI（如果已安装）
   • sherpa-onnx-offline（需要带有 encoder/decoder/joiner/tokens 的 SHERPA_ONNX_MODEL_DIR）
   • whisper-cli（来自 whisper-cpp；使用 WHISPER_CPP_MODEL 或内置 tiny 模型）
   • whisper（Python CLI；自动下载模型）
3. Gemini CLI（gemini），使用 read_many_files
4. 提供商凭证
   • 会先尝试已配置且支持音频的 models.providers.* 条目
   • 内置回退顺序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

​

配置示例

​

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

​

仅提供商（Mistral Voxtral）

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

​

仅提供商（SenseAudio）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
      },
    },
  },
}

​

将转写回显到聊天（选择启用）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // default is false
        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​

注意事项与限制

• 提供商凭证遵循标准模型凭证顺序（认证配置文件、环境变量、models.providers.*.apiKey）。
• Groq 设置详情：Groq。
• 使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。
• Deepgram 设置详情：Deepgram（音频转写）。
• Mistral 设置详情：Mistral。
• 使用 provider: "senseaudio" 时，SenseAudio 会读取 SENSEAUDIO_API_KEY。
• SenseAudio 设置详情：SenseAudio。
• 音频提供商可通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。
• 默认大小上限为 20MB（tools.media.audio.maxBytes）。超大音频会被该模型跳过，并尝试下一个条目。
• 小于 1024 字节的微小/空音频文件会在提供商/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 默认关闭；启用后会在智能体处理前，将转写确认发回原始聊天。
• tools.media.audio.echoFormat 可自定义回显文本（占位符：{transcript}）。
• CLI stdout 有上限（5MB）；请保持 CLI 输出简洁。
• CLI args 应使用 {{MediaPath}} 表示本地音频文件路径。运行 openclaw doctor --fix 可从旧版 audio.transcription.command 配置迁移已弃用的 {input} 占位符。

​

代理环境支持

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

​

群组中的提及检测

1. 如果语音消息没有文本正文且群组要求提及，OpenClaw 会执行一次“预检”转写。
2. 检查转写文本中是否存在提及模式（例如 @BotName、emoji 触发词）。
3. 如果找到提及，消息会进入完整回复流水线。
4. 转写文本会用于提及检测，因此语音留言可以通过提及门控。

• 如果预检期间转写失败（超时、API 错误等），消息会基于仅文本提及检测进行处理。
• 这确保混合消息（文本 + 音频）绝不会被错误丢弃。

• 设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true 可跳过该群组的预检转写提及检查。
• 设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 可按话题覆盖（true 表示跳过，false 表示强制启用）。
• 默认值为 false（当匹配提及门控条件时启用预检）。

​

注意点

• 作用域规则使用首个匹配生效。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），避免阻塞回复队列。
• 预检转写仅处理第一个音频附件用于提及检测。其他音频会在主媒体理解阶段处理。

​

相关内容

• 媒体理解
• 对话模式
• 语音唤醒